How are you dealing with documentation these days?

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.

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.

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

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.

Markdown and bookstacks.

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.

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.

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.

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.