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

• javelin

  1 16 9.0 Haskell

  Haskell implementation of series, or labeled one-dimensional arrays. (by LaurentRDC)

My workplace uses Confluence.

I hate it for a very simple reason: the code (in BitBucket) and the documentation are disconnected.

I want my code and documentation to be coherent with each other. For small open-source projects (e.g. https://github.com/LaurentRDC/javelin), I love using doctests which ensure some level of coherence between documentation and code.

• backstage

  125 26,317 10.0 TypeScript

  Backstage is an open platform for building developer portals

  

We use Confluence and markdown files in GitHub. I think we are moving a lot of our docs to Backstage [0] soon.

One process that ends up being really valuable for documentation purposes is our "Architecture Review Documents". This is a standard document that team leads fill out before starting work on a new Saga/Epic/Feature/whatever. It includes the scope and business value of a new feature or large block of work, high level technical architecture of implementation, the impact on existing database schemas and service APIs, etc. This document is presented in a meeting with technical leadership in our organization who deep dive on the topic and explore potential pitfalls in the plan.

The document and recording of that meeting live on forever, and this information is very useful when getting acquainted with a certain part of our product/codebase. You are able to read and hear clearly the intention of a certain service or module, and you can identify several relevant points of contact to ask questions to.

[0] https://backstage.io/

• WorkOS

  workos.com sponsored

  The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.

  

• documentation-framework

  54 89 5.5 Python

  "The Grand Unified Theory of Documentation" (David Laing) - a popular and transformative documentation authoring framework

  

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

• mdBook

  100 16,669 8.6 Rust

  Create book from markdown files. Like Gitbook but implemented in Rust

  

I'm responsible for a number of Java products. I try to provide high-quality Javadoc for all public library interfaces, library user's guides where appropriate, and development guides for applications. The latter two take the form of MDBook documents (https://rust-lang.github.io/mdBook/), with the document source living in the GitHub repo so that it's tied to the particular software release in a natural way.

Suggest a related project