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.
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.
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.
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 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.
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.
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.