Comment by GordonS
5 years ago
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.