Ask HN: How do you organize software documentation at work?

I generally like using a combination of the following:

* Wikis for general information, environment setups that are not project specific, etc.

* Repositories to host code and system specific information, usually in Markdown documents.

* Google Docs or Microsoft 365 for working documents that need to be collaborated on, commented on, and shared without the rigmarole of pull requests and the more static nature of wikis.

* Slack is for ephemeral information. If it contains documentation, specification, FAQ, debug steps, process explanations, etc., those should be captured and moved to the appropriate documentation location.

The one thing I really struggle with are diagrams. Cloud-based diagram tools like Visio and Lucidchart are great, but they are tough to save in a good location outside of the cloud environment. It requires exported the file and/or a PDF export. Then, these fit rather poorly into source-code control. There is the concept of "diagrams as code", but all of those systems are generally terrible at layout. There really is no good solution, as there are major trade-offs to both.

Everything in Markdown with the code.

Other parts of the company use Confluence, but the docs with the code are what I pour my heart and soul into.

Slack is always a good resource, but I'd hardly call it "documentation".

Fossil SCM, which comes up on HN every once in a while, rolls a wiki and issue tracker in the same repository as source code.

https://fossil-scm.org

I forget the terminology, but there's a good "grid" breakdown of documentation types (I think this one: https://documentation.divio.com ) that I've simplified a bit for the internal documentation I'm involved with.

* README, HOWTO, INFO, PROJECT, DESIGN, NOTES, FAQ

When I pull down a `git` repo, I read the `README.md` (of course). I make my own `NOTES.md` (eg: `.gitignore`'d) of what commands, environment variables, useful blog posts, search results, whatever. Rarely do I share or encourage sharing of `NOTES.md` wholesale, but it's helpful to be able to pull out a few snippets or re-orient myself when coming back to that software/project.

Then, other documents get prefixed with "HOWTO-Do-Some-Specific-Thing.md", or "INFO-Some-Particular-Component.md".

"PROJECT-...", and "DESIGN-..." are "dangerous" ones in that they can quickly fall out of date, but they can be very useful while they're being actively managed. I guess personally I've started making sure to include dates or "eras" in the title, eg: "PROJECT-[2024-Feb]-Add-Foo-Support.md" or "DESIGN-[2024-02-14]-...". Stuff that's outlived its usefulness can probably be moved to an `ARCHIVE/...` in case you need it later, but keep it out of the way from confusing newcomers 1-3 years from now.

"FAQ-..." almost never comes into play (hopefully) b/c it should mostly get absorbed into "HOWTO-..." or product improvements, and few products seem to rise to the level of needing FREQUENTLY asked questions. Ideally FAQ's would "go away" with work on the product or other documentation, but I've had some success with it as like sales-oriented (and ideally: sales-managed) FAQ / Canned Customer Response learnings.

Putting it all together you get something like:

  * README.md
  * HOWTO-Backup-to-S3.md
  * HOWTO-Backup-to-BackBlaze.md
  * HOWTO-Manage-Existing-Backups.md
  * HOWTO-Exclude-Frequently-Changing-Files.md
  * INFO-Supported-Backup-Systems.md
  * PROJECT-[2024-Feb]-Backup-9000.md
  * DESIGN-[2024-Jan]-Auto-Backup-Detection-and-Failover.md
  * NOTES.md (private!)
  * FAQ-Residential-Customers.md
  * FAQ-Business-Customers.md
  * FAQ-Backup-Recovery-Issues.md

Generally, they wouldn't all be "git-adjacent", but `README.md` should link to the other sources, `HOWTO-...` and `INFO-...` is generally good for your wiki/confluence/"published" documentation. PROJECT, DESIGN, and FAQ are all best as "loose" shared docs. Multiplayer by default with low barrier to edit/contribute. Sometimes DESIGN could be INFO-Design-..., or DESIGN might even be a DIAGRAM. You'll know it when you see it.

Prefixing the documentation with the TYPE has been super-critical in adoption. It clarifies that it's not "DOCUMENTATION-About-Some-Thing.md", but instead "HOWTO...(you're gonna do something, goal-oriented)", or "INFO...(you're gonna learn something, no specific outcome)".

If you START introducing new prefixes, then you'll hopefully see them propagate (as appropriate), but ideally whatever vocabulary your business/team ends up using is small (~5-10 documentation types) would cover a good 80-90% of your use cases, and they should be brain-dead simple enough that it's clear their categorization is useful.

https://app.diagrams.net (formerly known as draw.io) can be exported and imported as an XML. At one company we just exported the diagram as a png/jpg and as an xml, committed both to the wiki repo or source repo under the docs/ directory. Then next time, just import the diagram xml into the app and repeat. I think that's a good enough approach if diagrams are useful but updated infrequently.

I've started using a similar approach, minus the png/jpg, for my personal markdown based wiki.git, saving the xml as a file that I can reimport in the future. I usually do this for prototyping or grokking some new system.

edit: just remembed, github also supports mermaid diagrams, https://docs.github.com/en/get-started/writing-on-github/wor...