Comment by ChrisMarshallNY
5 years ago
I just use headerdoc-type stuff. Been doing it for decades.
It works very well, and doesn't really add any overhead to my work.
I write about how I do documentation here: https://littlegreenviper.com/miscellany/leaving-a-legacy/
It's a long read, because it's a big topic.
That's useful, but only covers documenting the code, and API usage.
Depending on the project, various other documents may be required, e.g. installation guide, user guide, operations manual, architecture diagrams, networking diagrams, module/component diagrams, information flow diagrams, high-level design, low-level design, docs at various "views" (such as "business view", "information view", "technology view"), design decision tracker, ontology...
Absolutely. I do those, as well. Here's a rather more intense example: https://riftvalleysoftware.com/work/open-source-projects/#ba...
I'm actually in the middle of using Postman to generate a more "modern" inline docset for a new engineer that is coming into a project that uses that server.
But I also like to keep docs to a bare minimum, as they become what I term "concrete galoshes": https://littlegreenviper.com/miscellany/concrete-galoshes/
We need to be very careful, as the docs can prevent agility, in a big way.
I find that if I can keep the docs pinned to the code, itself, as much as possible, it helps to keep some flexibility.
Ah nice, it's refreshing to see that level of documentation for an OSS project, even if it started as a commercial project.
Totally agree about not having too much documentation - sometimes outdated documentations is worse than no documentation at all.