Documenting design and code - Page 1
Forum section: electronics / general

author: Hawaka
author_rank: Regular Contributor
timestamp: August 16, 2025, 09:08:24 pm
content: Hello,For my work I’m currently trying to push that we document our product design more. We make electronic products that have power electronic, 1 or multiple MCU's, WiFi and a GUI. We do have version control: for PCB’s we track changes directly on a "History" schematic page and a BOM + PCB version, for the code we use SVN. We also use Redmine as a ticket tracker, but no one will ever look at closed tickets when looking for answers.What we are really missing is documentation on design decision, how the product works and how all the internal sub-assembly work together. We try to leave comment in the code and the schematic, but it is never enough to explain how it interacts with the rest of the product.I like how ReadtheDocs handles version and the general usage (experience purely based on the python docs), but I have no idea how easy/hard it is to implement / maintain.A few requirements:- Must be free- Must be able to have hyperlink in the text to go to other parts of the doc- Easy image / code insertion- Hosted locally (no cloud)- Easy enough to write documentation that all our engineer can do it. (I know that’s vague, but if we don’t have to learn a whole new language (like LaTeX) for it would be nice)Does anybody has experience on this topic?

author: Analog Kid
author_rank: Super Contributor
timestamp: August 16, 2025, 09:30:28 pm
content: I used to write computer manuals for a living. My experience was back in the 1990s-early 2000s, so of course my toolset would be a bit out of date, so take that into account.Back then I found the best tool to write full, extensive manuals was Microsoft Word. And I still use that for my own personal documentation.Word does allow you to put active links in a document, and even HTML links that will open in a browser. I haven't used the latter much so you'd need to experiment to see if that suited you. One thing I used a lot were page references, like "See page XX for more information", where Word would insert the target page number when reformatting the doc.Other than that, I had no real IDE, no magic interface to link documents, web pages, etc. Such a thing probably exists but I can't help you with that.You might try Word, see if it works for you. One nice feature is being able to create document templates so you don't have to reinvent the wheel every time you start a new doc. But that's probably pretty standard with a lot of apps these days.I can't emphasize, though, how crucially important it is to document stuff, so it seems you're on the right track there.

author: Nominal Animal
author_rank: Super Contributor
timestamp: August 17, 2025, 06:32:47 am
content: Host an intranet-onlyDokuWikiinstance.Before you laugh your ass off at me, let me explain why and partially how.When you first start something like this, human behaviour and especially the tendency towards minimal effort is your enemy. You have about exactly one chance of making thisobviouslyuseful to all its users, or you will fail. Documentation is a task that will truly succeed if done because it is seen as useful and part of the job at hand. If it is seen as a task that is donefor others, it will be allocated minimal cognitive effort and done to a degree that satisfies HR and admin types, but nobody else. You don't want that. And so, you'll probably also want to keep HR and admin out of it as long as possible; preferably with read-only access only.The reason for using a Wiki is that participation effort is minimized, expression maximized (especially if youinclude MathJax supportand other similar plugins that make writing the documentation easier than even in e.g. Word), and the structure of the documentation is up to you.Herein lies the trick of how to make such a closed Wiki work: you organize it to support your workflows and product development, documentthatwell on the front page, and require everyone to read that front page before giving them write access. Optimally, you'll have an introductory half-hour with pizza for everyone, and show how it's supposed to be used. Do not expect the initial structure to survive forever: it is supposed to grow and change as your needs and use cases change. Always keep an eye and an ear open for suggestions making it even better.To find out what the organization of your documentation should be, you talk to your engineers to find out about the "quiet knowledge" they have. You'll likely end up with some structured intertwined trees of information — for example, product history is likely one tree, software documentation another, and so on. Namespace plugins and similar can help with these structures. Hopefully you can have a small test group of engineers to help you design and initially fill the pages, because only by doing and using will you really know what works. Then, you quietly ask a few more of your engineers to check if they find it easy and useful, take in the criticism, and redo, until even they ask you to give them write access so they can start using it already. At that point, it is likely to be ready for wider use; not before.Even if you end up choosing a completely different approach, do consider applying the same logic: make it as easy to use as possible, organize it to be as useful for documenters themselves as possible so they spend the cognitive effort to make it useful (and enforce that as a policy), and try it out with a small set of engineers (that you know are willing to at least start the documentation efforts), to optimize the structure and policy before taking it company-wide.Full disclosure: I'm not familiar with herding engineers; I've worked more with scientists and artists and students instead.

author: thephil
author_rank: Regular Contributor
timestamp: August 17, 2025, 09:00:17 am
content: There are many options out there – e.g.MkDocsdocsifyVuePressDoctaveSphynxdocusaurusHowever, you may also consider something more pedestrian: Markdown + pandoc. We use it for writing software manuals and other kinds of documentation. The authors of the manual only need to know a bit of markdown and someone needs to build a nice looking template that everyone can use. Put the sources under version control (e.g. git) and you have great control over everything.

author: nctnico
author_rank: Super Contributor
timestamp: August 17, 2025, 10:10:23 am
content: I'd say MS-Word or Openoffice. Most people know how to operate MS-Word. I'm not a fan of Wiki style systems because these need a lot of maintenance to stay sensible. In a flat document structure it is much easier to see which chapters are already there so people can see where to add info instead of making a new entry which is a duplicate of an existing entry.However, I see myself moving to Google docs more and more because it is an easy way to work together on a document. I know the OP specifically wrote no cloud, but there certainly are advantages to using cloud based services for documentation.

author: paulca
author_rank: Super Contributor
timestamp: August 17, 2025, 11:00:44 am
content: The most successful I have ever used for "development documentation" is a wiki.You can set up some team "rules", like the last person to use the docs updates them or the first person to complain about the documentation gets a ticket to fix it.For all documentation you need to define it's purpose and it's audience or it will become a shit show when management find it and ask, "Can we turn this into a manual for the customer?"

author: MarkF
author_rank: Super Contributor
timestamp: August 17, 2025, 12:00:04 pm
content: If you're serious about documentation and willing to put in the time...Documenting your software takes a lot of time.For budgeting purposes, plan onTWICEthe time it takes to code for documentation.I worked on one program where management said we are going start documenting all our code.But, don't worry it's not going to take any additional time. They decided on the Wiki route.Long story short: NO documentation was ever written and the Wiki was worthless.I worked on many contracts for the military over my career. They have a whole series of documents,templates, design reviews, and procedures for their programs. To simplify them to their bare minimum,I would suggest two.-Software Requirements Specification(SRS), which states the WHAT. What does the program need to do.-Software Design Description(SDD), which states the HOW. How does the program work. This doc breaksdown the design into logical elements and describes their purpose and how they interact with other elements.It's a good place to define interfaces between systems (normally done in its own document).Pick your favorite word processor (MS-Word or OpenOffice mentioned above) and layout a template ofeach document for everyone to follow.Did I forget to mention, BOTH documents need to be complete BEFORE writing line one of code. Thisincludes peer design review meetings.I worked on a three year program with 12 developers. The first two years were strictly documentation.The third year was code and testing. I can not emphasize enough the time and budget required.If you wish to go further, useDoxygento embed into your code variable definitions and function descriptions.

author: Doctorandus_P
author_rank: Super Contributor
timestamp: August 17, 2025, 12:33:07 pm
content: I like asciidoc. It's a very simple text based format, and it can be "compiled" into THML, PDF, EPUB and a few other formats. I also have a plugin installed in Firefox that can directly interpret the asciidoc files. KiCad's documentation is also written with asciidoc.Asciidoc is quite similar to markdown. It's a bit annoying there are are a bunch of similar formats. Github uses markdown for the online documentation for each git repository. The syntax of Asciidoc is a bit more logical to me. II think that asciidoc is also a bit more "advanced" then markdown, but I have not used that much. I mainly stuck with asciidoc because it's used in the KiCad project.

author: NE666
author_rank: Frequent Contributor
timestamp: August 17, 2025, 12:37:58 pm
content: +1 for simple documentation formats e.g. markdown, stored in a DVCS e.g. git. The changelog can be as valuable as the content itself. Markdown can always be rendered in a 'prettier' way for consumption if desired, and there are plenty of tools available for that.For internal consumption I favour "less is more". Consider what value a document actually has and for how long that value will remain. I view it in rather the same way as writing comments within code; it's better a use of time to write and structure code/designs in a way that it is patently obvious what is going on, rather than adding comments to excuse bird's nests, poor nomenclature and general ugliness, or just to state the bleeding obvious. i.e. document the exceptions, not general rules and principles.Some high level interaction diagrams and docs are important but beyond that, I would only advocate documenting the "why and how" extensively in the specific cases and areas in which the implementation selected necessitates a particular approach AND the reason is non-intuitive. Otherwise, you're likely generating documentation that few will ever read, and fewer yet will keep updated.

author: SiliconWizard
author_rank: Super Contributor
timestamp: August 17, 2025, 01:36:54 pm
content: I mainly use LaTeX for more polished documents, and otherwise asciidoc. The only thing with asciidoc is that I have been using it for a relatively short while, and I still don't quite know how to properly write themes for it. The default themes are ok for HTML output but the PDF output is much too "bland". If anyone has pointers for theming asciidoc, that could be cool.

author: nctnico
author_rank: Super Contributor
timestamp: August 17, 2025, 04:14:04 pm
content: Quote from: MarkF on August 17, 2025, 12:00:04 pmIMHO this needs some nuance. Nowadays nobody is creating a full specification before starting to code because requirements change faster than you can keep up with. For modern day software you define the super structure (skeleton) which can hold the data structures and functionality but you are not going to build everything in one go. It is like building an office building incrementally. The super structure is there but you decide on how the office spaces are layed out and how the exterior should look like for each floor later on. The biggest trick is to put the supply lines, elevators and plumbing in places where it is going to be needed later on OR make those facilities versatile enough so there is some wiggle room. It takes foresight to do this right and it actually is harder to get right compared to a top down approach. No, agile is not some kind of wonder drugQuoteNo, doxygen is going backwards. Doxygen adds nothing which helps to understand how a program works or how to use an API. A good IDE (like Eclipse CDT or VS code with the appropriate plugins) can tell me exactly the same (and more) as doxygen generated crap but then updated in realtime.What you need is the information about how the functions work together. What is the overall functionality? How does data flow through a piece of software? People think that the doxygen output is great but that is due to the fact that the author of a piece of code understands how it all works together. But that is still in the person's brain, it is not written down somewhere. Added to that is the fact that people have different ideas of what is a logical way to implement something. All in all that leads to a huge disconnect between the author of the code and the person who needs to use / modify code.For example: I've been using a rather large library from Microchip for a project. This comes with documentation containing a few coding examples but the rest is doxygen generated crap. What I need to know is the coherency between the functions but that information simply isn't there. In several cases I resorted to writing my own functions which access registers directly because that is quicker / easier compared to figuring out which functions to use from the API.

author: John Coloccia
author_rank: Super Contributor
timestamp: August 17, 2025, 07:21:45 pm
content: Quote from: MarkF on August 17, 2025, 12:00:04 pmJust a small tweak. The SDD usually describes the individual functions or units that the developer needs to implement. This is sometimes useful, and sometimes not. Sometimes required, sometimes not.And architecture document is more useful. Show how the big pieces interact, design philosophy, where's the data going, etc.Documentation is never easy, on real projects much of it lags (or is out of date) with the actual project, and basically this is why waterfall is almost the worst way to run a project. The only worse way I can think of is diving is with NO clear vision at all.Big 'A' Agile is almost as bad, and even the creators have since said, "hey...this isn't what we had in mind. Use your head."

author: Analog Kid
author_rank: Super Contributor
timestamp: August 17, 2025, 07:41:49 pm
content: @Nominal Animal: Regarding your post above where you suggest using DocuWiki:Have you actually ever used such a thing, or participated in a group doing documentation as you describe?I used to earn my living as a technical writer writing manuals, but I worked solo for the most part. Never was part of a group, except once when I was involved in user-interface design for a product: that was an adventure in frustation. I remember at one point being accused of promoting a "Fisher-Price user interface". So I have little idea how a collaborative approach to documentation would actually work.Point is I've never "herded engineers" either, so I'm wondering how that part of the equation works here.

author: Hawaka
author_rank: Regular Contributor
timestamp: August 17, 2025, 07:48:58 pm
content: MkDocsdocsifyVuePressDoctaveSphynxdocusaurusasciidocDocuWikiThanks for all the suggestion, I will look into them. At a first glance the end result looks kind of all the same, I guess it will come down on using/writing it.I agree that doxygen is useless on a product level. I have tried Word/OpenOffice in the past for documentation, wasn’t happy so I’m open to try something else.The documentation will be solely for the engineering team, no need to consider user manual / end customer.

author: Nominal Animal
author_rank: Super Contributor
timestamp: August 18, 2025, 07:30:40 am
content: Quote from: Analog Kid on August 17, 2025, 07:41:49 pmNot for software or hardware development; only for server documentation, issue logging, and such.I have dealt with related issues — essentially getting information out from individual people and intoanykind of written system — quite a few times prior to 2011, however, in various contexts including software/multimedia development, internal and public web stuff, and so on. It has always been a pain, because the organizations never integrated this into the workflow, and just made it aseparate task. That just will not work, when the information is known only to specific people.In essence, I know that offline documentation will not generally work, because it adds several steps to the process of documenting. It might work with software engineers who are used to version control systems, but everyone else will see it as just overcomplicated. It has to be easy to edit and immediately presented in rendered form (and that means various simple markup formats like Markdown, asciidoc, Wiki markup, et cetera). I know that when the documentation is aimed at "others", minimal cognitive efforts will be spent, and only to "get it done", not to make it work or be useful. It has to be part of everyones workflow, and that means authorship needs to be tracked, preferably per changeset; team leaders might wish to occasionally check if all members are documenting their work, so per-contributor change lists are useful. I know that if you assign a person or a team to manage the documentation, they will be trying to pull information out of reluctant people (because it seems like a waste of time or extra burden to them) like they were pulling teeth out.For internal documentation, we need something trivially easy to use, fast to search, versioned with history, authorship tracked per change, and without an externally imposed structure, to overcome all these issues. A wiki-like tool seems like the perfect toolkit for this to me. What it does not tell/impose is the structure and formatting, because those will vary from organization to organization, and almost certainly needs to be developed using a specific product to see what is needed. And because needs will change, the Wiki structure and use will change in time, too. Therefore, making it self-documenting is crucial (as in, the "front pages" will describe what, where, and how; and even those can and will be changed as the needs and use patterns change).Quote from: Analog Kid on August 17, 2025, 07:41:49 pmI agree: a Wiki would not work for that — except as an adjuct, perhaps to collect FAQs and example cases.Quote from: Analog Kid on August 17, 2025, 07:41:49 pmI once did both content and UI design in a team with a graphic artist and an UX specialist, as the technical/implementation specialist. This was way back around the turn of the century, with multimedia delivered on CDs and images on the web had to be optimized for file size or users would complain about the extremely slow page loads. Our domains of expertise overlapped just enough we could fully trust each other, so it was actually a very, very nice experience. Some of my best work, too, I guess.Quote from: Analog Kid on August 17, 2025, 07:41:49 pmNote that I do not treat this as a separate documentation task at all. I am considering the question here as"how to get my engineers to document what they did and why?"which is more akin to generating a task log than documentation for others, except that it is the"why"part that is the key point, pulled out of the engineers' brains, and put in writing somewhere.Stuff like user manuals and technical reference manuals are different. They describe the available interfaces. In good C/C++ software projects, you find that information duplicated in the header files as comments, as docstrings in Python modules, and so on. Yet, those are just a small part of the entire documentation.Consider the case where a client comes with an API extension request to achieve some task. How do you evaluate such requests? Well, in my opinion, to evaluate such requests rationally, one needs the deeper documentation, and find out whether it is possible, if it will conflict with existing solutions, and so on. It isthatstuff that I'd put in an internal-access-only Wiki. Hopefully, when the engineers decided on the API to expose, they also added notes as to what else could be exposed later if there is need (but shouldn't be exposed from the get go because it might limit future development; backwards-compatibility is always a burden on future freedom of design).How sure am I that it would work? I know it can be a very easily integrated into typical workflows (only needing team leaders to check each engineer does add such notes on whatever they're doing, and prodding them if they're skipping the documentation part). Compare to e.g. rejecting version control changesets with zero documentation. It is for the stuff an engineer would tell to another engineer working on the system, noting the benefits and limits of each approach implemented, and the alternatives that were discarded and why. Instead of talking over a coffee where the quiet knowledge is transferred and vanished when neither of them is present, it is logged to the Wiki. In a sense, it is more like a structured log that every engineer would be required to maintain in relation to their own work, and not at all like a manual. But, if the information is there, then a TRM or user manual could be written based on the information in there.

author: nctnico
author_rank: Super Contributor
timestamp: August 18, 2025, 07:49:41 am
content: Anything with self... like self documenting, self managing, etc ain't going to work as people are lazy and defer responsibility if they can. And self documenting software doesn't exist because documentation needs to explain why something is implemented the way it is while software only shows how it is implemented. In the end you need to tell (most) engineers what kind of documentation you want and allot time to do it.

author: paulca
author_rank: Super Contributor
timestamp: August 18, 2025, 08:19:44 am
content: Military? Makes sense. Although you are kind a missing quite a few steps.https://www.lucidchart.com/blog/pros-and-cons-of-waterfall-methodologyOutside of military and some lingering governments, nobody uses "Waterfall" as it simply cannot move as fast as technology does. It results in the "Golden Gate Bridge painting problem".It resulted in "Government Modernisation Projects" aimed at "catching up". They were waterfall too. The single biggest category of software failure the industry has had.You CANNOT paint it fast enough and be profitable.So what really happens?They want it to be faster. So the pressure the people who actually do the workCustomer + Consultants write requirements.A year laterMostly a new team tries to organise the requirements into some fashion of order.6 months laterThe customer completely trashes all of that work by demanding it be done in the LEAST technical conceivable fashion they could come up with.... years pass ...Suddenly, having taken 3 years or more to "formalise" and "sign off" the requirements, they dump it on a dev team, clap hands and say, "Make a spec".The reality is the dev team are all brand new, nobody on the project was on it when the docs where written. Not even teh customer remembers the requirements.And here is the crux. At this point, "nobody has a clue anymore" waterfall REQUIRES you go back to the start.Do you think that businesses do this? Hell no! They just put more pressure on the dev team to "get on with it".So you have docs that don't add up, make sense and are full of holes and contradicitions.However YOU GET 3 WEEKS!

author: RJSV
author_rank: Super Contributor
timestamp: August 18, 2025, 08:32:36 am
content: Experience at Qantel Business Computers was to observe a large organization that had a devoted department, I.E. 'Training and Documentation' Dept. and, believe me, those folks were professionals, training customers, visiting for special training sessions.Also, they trained the numerous field engineers that staffed offices around the country, and beyond.This large documentation dept. was intimately entwined with the regular engineering functions and (probably) under the wing of the Engineering division as a whole. I say that because some (other) groups or corporate structures have the documentation (and field services) under the wing of 'Marketing'. (Which, to some degree would also make sense).The Qantel dept mentioned had, maybe 12 to 15 employees. Most big departments doing just 'drafting drawings' would be more closer to 4 or 5 employees, in total.

author: hans
author_rank: Super Contributor
timestamp: August 18, 2025, 09:06:10 am
content: I fully agree with nctnico here.Code is an implementation.PCB is an implementation.Schematic is an implementation, sometimes barely more readable than a PCB.Some years ago, I worked at a vendor of after-market kits for automotive-like vehicles. These kits had to interface with various machines of which none were documented. For a proportional PWM system, it contained a 20A H-bridge even though it didn't specify anywhere how much Amps the load could actually pull. There were no thermal calculations, etc etc. The whole design was built around "good enough".To make things worse, the schematic and BOM were manually supplemented for each production revision, which made it hard to guess which version was leading. Again, this is especially annoying when you can't ask the designer because he left, but you can see 3 revision of production boards with all kinds of bodges and changes around certain parts.This is where some documentation system could come in. Heck, it doesn't have to be a wiki, but perhaps even an issue tracker on your Git repo host. No work is allowed to be performed when no issue is attached. This forces someone to write down what actually fails or triggers a bug, how to reproduce it, and then finally how the issue got resolved. These changes can then later on be ported over to a more comprehensive design document, preferably also kept per design version/revision.In school we were trained in the waterfall/V-model, but I was never a huge fan of it. It fits hardware better than software (< which has way more 'agile' or better design techniques nowadays). But even for hardware, it may help to make a prototype with a bottom up approach, to get hands on feeling with the tech you're working on and see which residual side effects need to be resolved at a higher design layer. Its not always possible to foresee all of these problems beforehand or without ever touching 1 line of code or soldering iron.For the V-model I find it hilarious that it suggests in plain sight what the most expensive design mistake is: any requirement drafting error. I think for industry, its ignorant to say these cannot or should not happen, because sales will also come in calling if product can support XYZ as well.

author: Nominal Animal
author_rank: Super Contributor
timestamp: August 18, 2025, 01:29:56 pm
content: Quote from: nctnico on August 18, 2025, 07:49:41 amBy "making it self-documenting", I meant that the documentation tool use should be documented by the tool itself, and its maintenance use the same processes you apply to the documentation. That is, the way documentation is done, should evolve as the engineers' workflows evolve, and use the same mechanisms.This is so that your documentation does not become a rigid external task that "just has to be done for nobody knows why", like logging what you do and for which project at thirty-second intervals. That shit gets sidelined fast by intelligent people. There is no reason to make a yet another task to please beancounters or add a yet another graph widget to your Cxx's desk toy displays to impress potential investors. I only suggest what I would be willing to do myself.Quote from: nctnico on August 18, 2025, 07:49:41 amYes. This is exactly why I emphasized that documenting the reasoning behind choicesmust be a part of the work flow, and enforced by team leaders. And how that kind of a tool must be lightweight, minimum-latency (no compiling to get the visual version), and so on.The lazy ones who do stuff but don't document it, youfire, no matter how brilliant. Because brilliant today is hellishly expensive to maintain a year from now. There are enough drive-by brilliance already, and it is thegood, diligent developers that have to carry the development debt burden with zero gratitude or recognition. Guess why I know?If you want your product to be maintainable for longer than the current quarter, you reward those engineers that produce most maintainable code, not those that produce most lines or features.

author: Picuino
author_rank: Super Contributor
timestamp: August 21, 2025, 05:34:13 pm
content: My entire website has been built usingSphinxwith theReadTheDocs thememodified:*https://www.picuino.com/en/electronic-diodo.html(The website is originally written in Spanish and has an automatic translation into English, which is why the English version is not well written).Initially, using reStructuredText as the markup language was a little difficult, as it is very comprehensive and rich in keywords. However, once I had familiarised myself with it, I appreciated having so many options and not having to implement exceptions with HTML as I would have had to with Markdown.The code documentation is straightforward and incorporates automatic highlighting. Although Sphinx was developed specifically to document the Python programming language, it can be used for any other language or any other documentation.I would highly recommend using Sphinx as a static website generator for documentation.You can also use GitHub and ReadTheDocs together to publish documentation. This seems like a very flexible option, although I can't say much about it as I haven't used it myself.EDIT:I believe Sphinx meets all the requirements you indicated in your first post- Free and open-source- Able to have hyperlink in the text to go to other parts of the doc (easy)- Easy image / code insertion- Hosted locally (no cloud)- Easy enough to write documentation that all our engineer can do it. (markup language easy for an engineer)- Formulas can be embedded.- Several outputs available: HTML and PDF are the most usefulEDIT 2:As Nominal Animal has already pointed out, the problem with Sphinx is that you need to compile to see the updated version with the new changes. While compiling small changes is quick, it is still a significant handicap.

author: John Coloccia
author_rank: Super Contributor
timestamp: August 22, 2025, 01:51:38 am
content: I personally have a hard time understanding all the different ways people use the word "documenting."Because yes, there is code that is basically self documenting and needs extremely few code comments, and frankly that should be the norm. And this is not what documenting software means to me. Because I'm pretty fluent in programming languages, so I don't need a translator from idiomatic code to "what are you trying to do?", anymore than I need someone to translate English to English. Unless you're doing something completely stupid, I can read your code. And if you're doing something stupid, I'm kicking it back until you make it idiomatic or comment it in a way that makes sense.And this has nothing at all to do with actually documenting the design of your software, which is what most people think when they think of documentation. Because I don't care what you're little functions or methods or whatever are doing (unless you've written them so stupidly that you need to write big long paragraphs explaining what you're doing). I care about how the pieces fit together.

author: RJSV
author_rank: Super Contributor
timestamp: August 22, 2025, 06:32:36 am
content: Interesting.I tend to view this as a fragment of the whole organization, meaning that 'quality' maybe cannot be forced into an employee, they need to be self-motivated to expand effort on quality documentation.When viewed as a whole; arguments start (within your organization, department, whatever). Meaning that some in your office could be saying the documentation is wasted nonsense, as administrative paperwork (that no one really reads).Then, in contrast to that, we also have the more formalized military spec. things, where attempts to standardize your spec. and related very formal 'Quality Standards'. I'm a bit lost to recite what kinds of effectiveness those formal, military inspired standards produce.But I know the games: where specifications get cranked out with very little imagination. OK so, tell me: How did Apple Computer do their early documentation, and how useful was/is it ? (From the time period 1977 to maybe 1990).Of course, some departments simply repeat the requirements back, parroting like we've seen A.I. do."The 14 bit multiply routine uses a 14 bit register and proceeds to multiply, using multiplication algorithm."Those sorts of comical parroting have examples everywhere.So, it really comes down to individuals, I think, who document by imagining which portions may be novel, and pointing out to readers the unexpected angle or approach taken."We figured a way to skip using carry-borrow flag, until later in the code...". That gives a document reader heads up, on some non-standard section or math use that is surprising.Sorry, but documentation, proper, is elusive aspect, in the creation process. I bet many very excellent coders cannot even convey what day it is, accurately, which is a complement for some genius types (that can't dress properly).You get some kind of helpful results, hit or miss, it seems...just sayen

author: Nominal Animal
author_rank: Super Contributor
timestamp: August 22, 2025, 07:31:40 am
content: Quote from: John Coloccia on August 22, 2025, 01:51:38 amFor me, code comments should indicate developer intent, not describe the code at all. What do you mean by "how the pieces fit together"?As a first approximation, internal project documentation should answer all "why" and "why not" questions. Code documentation describes externally visible interfaces and major algorithms ("how"), and should describe the assumptions involved, and which algorithms and approaches were chosen and why, and which ones were rejected and why. If your UI uses synchronous interfaces and not asynchronous ones to the system state, it should tell why that is. If a project stumbles on the same roadblock twice, it is a badly run project. If its bus factor is small, the internal documentation is insufficient. If new developers are onboarded by giving them read-only access to the sources, instead of made to read the documentation throughfirst, the documentation is not done right nor used right. When a new developer asks questions not yet covered by the internal documentation, their answers should be added there.(It is much easier to drink from a firehose and dig through tens of thousands of snippets of information, than to interrogate a developer that died in a car accident. When each question one asks is answered by"Ask personZ, they're the one that knows that part", the project is badly run and doomed.)

author: felixd
author_rank: Regular Contributor
timestamp: August 22, 2025, 07:44:01 am
content: Why nobody is mentioning Git? BTW, why are You using SVN???* Gitlabhttps://gitlab.comGitlab can be self-hosted if You don't want to put code online (privately or publicly)Gitlab supportshttps://Draw.ioWith above solutions You can use Markdown to document projects. Markdown is super easy to learn.Both have Wiki's for projectsBoth have Issue tracking for projects.Both supports hyperlinks.Inserting images is just Copy & Paste while creating Markdown document, creating new Issue/Request or putting a comment.Both are freeI am quite sureGitLabis what You are looking forPaweł.

author: paulca
author_rank: Super Contributor
timestamp: August 22, 2025, 09:25:07 am
content: The real trouble with documentation is keeping it up to date.The real trouble with out of date documentation is it's WRONG!This can be worse than no docs.

author: voltsandjolts
author_rank: Unknown
timestamp: August 22, 2025, 09:46:21 am
content: Quote from: felixd on August 22, 2025, 07:44:01 amSIX people mentioned already!

author: Picuino
author_rank: Super Contributor
timestamp: August 22, 2025, 10:00:47 am
content: Quote from: felixd on August 22, 2025, 07:44:01 amThe problem with Markdown is that it is too simple, meaning that generating and maintaining documentation can sometimes be difficult.I often use tables and much prefer the reStructuredText syntax for this purpose ( .. list-table:: )With reStructuredText, you can add a table of contents for the current page anywhere you want on the page.You have greater control over the size and position of inserted images, and you can add comments to them.ReStructuredText is a more complete and powerful markup language than Markdown. That means you won't have to constantly switch to HTML (which is very cumbersome) to get the results you want.And GitHub supports reStructuredText.

author: paulca
author_rank: Super Contributor
timestamp: August 22, 2025, 10:08:25 am
content: Git is fine for purely technical documentation where the only audience are the devs with git access.This is a small subset of the documentation required in anything but a mickey-mouse project.Once you get into "proper" software for governments, banks, military, or "mission critical" and in some cases, even automotive, the documentation requirements, a lot which are legal requirements goes up dramatically.These documents are not "single audience" and cannot go into git. 99.9% of the time these documents are related externally and then bind the development team.The development and test teams however are responsible for producing quality audit style documentation, static and dynamic code analysis, trace-ability matrices and so on and so forth.In these styles and scales of project documentation is king. Development is slow and combersome and usually budgets and timelines get doubled.The modern thinking for development outside of these "critical" and "documentation/regulation heavy" contexts is that documentation should be kept to a minimum and kept up to date. The mantra is, if your team are moving at the right speed your documentation will be out of date before the toner is dried. Documentation becomes a burden not an asset.As I said, there are only a few things worse than no documentation and they are, "Wrong documentation" and "Out of date documentation".DO NOT create out of date documentation willingly.If you look at most datasheets, as an example of this down well. They try to aim for a high % of useful information and a low % of useless information. The datahsheet is as long or as short as it needs to be and only what it needs to be.Similar "minimalist" and "easy to update because low volume" documentation approaches are needed.The reality today is, it can take a developer 15 minutes to code a ticket, an hour to test it and the next 3 days to document it.If you are a software company in the market today, you cannot afford those 3 days, because one of your competitors will skip it.

author: paulca
author_rank: Super Contributor
timestamp: August 22, 2025, 10:15:21 am
content: Quote from: Picuino on August 22, 2025, 10:00:47 amI want to save you some embarressment.When you get sent "on site" to a customer, you don't automatically get an internet connection. In fact you have to go through a long winded, multiple hour process to get one. Then you will find that you won't be able to access github or anything useful or download anything useful... or use "ssh" channels because they gave you a "Guest" wifi account.I have been here. I was stupid enough (at least once) to not download and "generate" everything, including documentation, BEFORE, getting on the plane. It's uncomfortable to say the least.So, if you have unreadible XML, MarkUp/Down docs that need compiled and you don't have a "generated" copy, you better hope you IDE and tools work 100% off line.

author: SteveThackery
author_rank: Super Contributor
timestamp: August 22, 2025, 06:11:21 pm
content: Quote from: paulca on August 22, 2025, 09:25:07 amIndeed. The solution is simple: you insert several blank lines at the top of each code file, and declare this to be the 'virtual comments' section. It has the wonderful advantage of never getting out of date.

author: Picuino
author_rank: Super Contributor
timestamp: August 22, 2025, 06:44:41 pm
content: Quote from: paulca on August 22, 2025, 10:15:21 amFor better or worse, Sphinx only works offline.I usually compile reStructuredText sources to HTML format locally and then upload them to GitHub.

author: Hawaka
author_rank: Regular Contributor
timestamp: August 22, 2025, 06:50:24 pm
content: Quote from: Picuino on August 21, 2025, 05:34:13 pmNice website, I like the falstad integration too. Looks fancy!Having to compile every time is a real downside, but maybe it isn’t after all. As long as the process is a few second long, I would say it’s the same problem as writing microcontroller code. You always have to compile and run it to see if what you did works.Quote from: felixd on August 22, 2025, 07:44:01 amWe are using SNV for 2 main reason, legacy and it does everything we need it to do very easily. I cannot say about gitlab, but I am going to assume it’s about the same experience as github (which I have experience with). I find that git / github is quite complex if you only need the most simple feature. We are a very small team, all in-house, only the people writing code are using SVN and our repos are quite small. Why make it complex if not needed?Quote from: paulca on August 22, 2025, 10:08:25 amDocumentation will be 100% only for the engineering team, as said before. Documentation requirement is only as important as either one of your superior say so, or as much as you can do it until superior disapproval. So I wouldn't dare to express the documentation in relation to the complexity of a project...

author: RJSV
author_rank: Super Contributor
timestamp: August 23, 2025, 04:18:29 am
content: Took a second to glance at Wikipedia to refresh my memory, of Unix SCCS system, for keeping revisions ID and change history.That was, circa 1987, the 'C' and Unix world to be; it just didn't take on like predicted. (Instead, lol, we maybe got 64 bit assembly language capable systems,...and very fast, compared to 40 years ago.One place (Snap-On scanner coding) I did obtain the books, on SCCS. That's Source Code Control System, that was helpful while contemplating installing (any) similar system but for our assembly language. An attempt that was starved of time, but I had wished to get more effective group control, as tracking assembly language edits gets bulky.Coincidentally, in that same vein, another assembly language, single chip 4/8 bit micro, at another company, had occasional needs for better tracking of edits, (and why). That was Davis Instruments, maker of personal backyard weather stations, including wind speed and temperatures.Doing, or attempting hybrids, of SCCS and our less formal habits, around the offices.- - Rick B.

author: paulca
author_rank: Super Contributor
timestamp: August 23, 2025, 09:22:27 am
content: Quote from: Hawaka on August 22, 2025, 06:50:24 pmI have worked in two different sectors/industries with heavy "governance" and "regulation".The contrast is staggering and the reason is fairly obvious.Banks and Governments.Both produce documentation. Both require documentation. Documentation there has "legal teeth" and costs millions or billions through it's quality.In banks. The documentation is lean, simple, sharp, detailed and exact. When money is lost, or reputation is lost due to mistakes, it is a MAXIMUM severity event. Every penny is accounted for. Money is spent directly to stop further loss.In governments... It's someone elses money and they don't give 2 shiz. They write LOTS and LOTS of rubbish documentation give it to coders directly and expect working software. When we complain they ask us to write the documentation. Yet they don't give us access to the people who know what the software is meant to do.... even IF those people exist at all. When of course they get delays, bugs, non-functional garbage.... they shrug. Not their money. "Let's just go procure some more tax payers money"