What tools and processes have been working at your company to derive the most value from documentation?

Has any of it changed in recent years?

I don't. I gave up.

In my 20+ years nobody has ever maintained the docs and we all somehow made it.

Businesses and careers don't rise and fall based on whether or not a readme file is up to date.

Also, in the age of AI producing an explainer takes minutes. I've delivered full reports on how a system feature everyone forgot about works in about 15 minutes.

Before LLMs it would have taken me weeks to produce the same document.

Everyone says they will keep that random wiki page up to date. They never do.

I trust a few specific types of docs:

1. Commit messages/PRs — I feel better piecing together reality from pull-requests, commit messages, and any associated artifacts at the time of the change. I trust these to have been true at the time of the commit, but quickly decay. The more decisions tracked there, the easier it is for me to put together a mental model of important pieces of the system. (Conversely the more decided in a random meeting or slack thread, the less anyone in the future gets)

2 Executable/testable docs - Alternatively any actual documentation purporting to talk about “now” should be made executable. I (or AI) should be able to run it and verify it against the system.

I'm the only person who writes documentation in my department. I continue to do it for my areas, but I'm unsure if it's out of commitment to the mission or spite after failing to get anyone else to write.

I used to write documentation extensively for everything I encountered, and people appreciated it. However, no one else wrote or even added to the documentation.

I got tired of being the only one, so I stopped doing that. Now I just assign issues to people. It got some of them to write really poor documentation, composed of random paragraphs and disjointed bullet lists that don't make sense to anyone but themselves. I stopped getting annoyed by it. If I can't instantly grok it, I just reassign the issue to them and forget about it.

At my last gig it was Notion, and I hated it.

I prefer markdown in a repo for developer docs.

Confluence was ok

A well set up google doc structure worked the best but was tedious to set up and I don’t love living on google.

1. Documentation driven development - write the explanatory docs before the feature or project in markdown.

2. hitchstory for executable tests that generate up-to-date how to docs with screenshots or whatever. I tend to write all how to docs as tests.

3. OpenAPI for API docs. Sometimes I have scripts that generates lists of enums too, etc.

4. Some sort of script that ties all of the above together and generates a documentation artefact on each build.

At my company, we like to own our own data for websites and documentation. So it rules out most of the 3rd party options. We self host using Docusaurus (static site generator) and Decap CMS for editing (formerly Netlify CMS). We then host it on Cloudflare Pages.

Markdown in the code. It was originally a way to aid AI, but having the documentation on design systems in the same folder as the design system is just sensible when we think about it.

The biggest drawback for documentation is it goes out of date, which is far worse than no documentation. Rather than drop them in confluence, where they also litter the docs, it's easiest to place them neighboring the affected files and update them there.

I push for markdown in git whenever I can. You can autogenerate markdown, you can parse it, you can test it. You can version it, you can branch and merge it (and so include in "done" criteria), you can diff it. You can use your coding AI agent to search it (and update it). It's just files.

You can in principle do it all with other approaches, but it is much harder or clunkier. And with tools like Obsidian the end user experience eith Markdown can be absolutely as friendly and nice (or nicer) as with Confluence or Notion.

Docs live with The Thing. If people need to find or remember them, they will be obsolete.

Forever at odds with Business People who like to see Confluence and the Working People who maintain/use it elsewhere.

Markdown in the repo, might get mirrored. Maybe. One day I'll grow up and do pandoc

Markdown and bookstacks.