11–20 of 93 posts
Never use a wiki for anything. Wikis are the number one worst form of documentation. They are worse than no documentation. Wikis explicitly destroy the concept of ownership and responsibility, and without those, what you get is a big pile of outdated, unorganized trash that no one maintains. Destroy wikis.
So what do you use instead?
I hate, hate software documentation as a concept. It gets out of date and is hard to use. It's a last resort, only for specialized cases. I prefer two types of documentation: 1. Executable documentation - tests, asserts, even things like Jupyter notebooks that can be tested and executed 2. Timestamped documentation - documentation that has a clear date on it of when it was valid. So the reader has an expectation "Thi…
The documentation lives in the same git repository as the code that it documents.
Inaccuracies or out-of-date documentation is treated as a severe bug. Issues are filed, the documentation gets fixed.
This is crucial, because if zombie documentation is allowed to persist it causes people to lose trust in the documentation, which means they won't refer to it and they won't contribute to it.
Once the documentation is in a trustworthy state, keeping it that way gets a LOT easier. It becomes part of the code review process - a PR won't be accepted unless it updates the relevant documentation that accompanies the code change.
I've been using this policy for my own projects for quite a few years now, and the result is that I'm proud of the state of my documentation for almost the first time in my entire career.
Never use a wiki for anything. Wikis are the number one worst form of documentation. They are worse than no documentation. Wikis explicitly destroy the concept of ownership and responsibility, and without those, what you get is a big pile of outdated, unorganized trash that no one maintains. Destroy wikis.
So what do you use instead?
Bakes into your existing workflows, direct line of accountability to both the code reviewer and the dev.
The editing software can be anything really.
Never use a wiki for anything. Wikis are the number one worst form of documentation. They are worse than no documentation. Wikis explicitly destroy the concept of ownership and responsibility, and without those, what you get is a big pile of outdated, unorganized trash that no one maintains. Destroy wikis.
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.
Never use a wiki for anything. Wikis are the number one worst form of documentation. They are worse than no documentation. Wikis explicitly destroy the concept of ownership and responsibility, and without those, what you get is a big pile of outdated, unorganized trash that no one maintains. Destroy wikis.
So what do you use instead?
Especially if making changes to the over all architecture or introducing a new dependency! The team shouldn’t let the PR ,edge until the docs are sufficient
I span up a search engine that covered as many of those systems as possible (just SQLite FTS with Datasette, cron tasks that indexed various things and a simple custom search UI) and it helped a lot, because people at least had a fighting chance of finding stuff.
I believe there are off-the-shelf solutions for this kind of thing now, though I don't have experience with any of them myself.
I've since recreated aspects of the search system I built there as https://github.com/dogsheep/beta - you can see a working example of that system on the Datasette site here: https://datasette.io/-/beta?q=geojson
Earlier quoted context omitted.
So what do you use instead?
Assign domains of the app to developers, the people doing the code reviews require people to update documentation. Bakes into your existing workflows, direct line of accountability to both the code reviewer and the dev. The editing software can be anything really.
People like to say “Slack isn’t documentation” but in reality it’s a better documentation than some outdated Wiki nobody is touching.