2 ms·
The documentation that needs to be kept 100% up-to-date is the usage documentation. Here's how to use this Python class library. Here's how to use this REST API
by simonw 2y ago
The documentation that needs to be kept 100% up-to-date is the usage documentation. Here's how to use this Python class library. Here's how to use this REST API. Here's how to use this CLI tool.
THAT should live in the same repository as the code itself, and updates to it should be enforced as part of code review.
Design documentation that describes the process that got to that point should live separately from the repo in something like GitHub Issues, because it's not guaranteed to be up-to-date but can still be referenced during code archaeology sessions when trying to figure out WHY the software is the way it is.
Commit messages work too, but I prefer to have a short commit that links to an issue thread where I can find out more.
I wrote about this here: https://simonwillison.net/2022/Oct/29/the-perfect-commit/#documentation https://simonwillison.net/2022/Oct/29/the-perfect-commit/#do...
- kmoser 2y agoAgreed about code usage documentation, although it's nice to have a more robust manual with several nicely formatted usage examples, which would be too much to put in the code as comments. In my mind, the design document doesn't have to describe everything that got to the present point. It should describe the current working of the system, which parts talk to which, what protocol they speak, the details of any custom protocols, what the DB schema is, system architecture, why a certain index exists and why other indexes were explicitly omitted, etc. It doesn't have to contain every one of these things (perhaps the schema definition goes in the code repo) but these are the types of things I think it should have. It can certainly contain notes like "We used to do X but because of Y we now do Z instead" but that's not as necessary. I would argue that such a design document is essential for keeping everybody on the same page. How else will you know the overall design? If you can fit all that documentation into comments in the code repo, great, but then you don't have a single point of reference to guide you; instead you have to hunt all over for comments that are stored disparately, and there is no overall narrative.