Ask HN: How are you dealing with documentation these days?
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?
Has any of it changed in recent years?
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.
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.
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 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.
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.
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.
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.
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