3 ms·

But then how do you communicate the latest consensus on all issues, e.g. for a newcomer who doesn't want to slog through months of communication, or a team memb

by kmoser 2y ago

But then how do you communicate the latest consensus on all issues, e.g. for a newcomer who doesn't want to slog through months of communication, or a team member who has been part of the thread all along but can't easily find where the team agreed on a particular thing? In other words, how do you summarize the thread into final documentation?

softwaredoug 2y ago
Well unfortunately there’s never “final” design documentation. Design docs go out of date pretty fast. I think it’s healthy to treat design docs like a historical artifact - true at one point in time. It’s less likely they stay up to date to reflect reality.
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 ago
  Agreed 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.

by kmoser 2y ago

softwaredoug 2y ago

Well unfortunately there’s never “final” design documentation. Design docs go out of date pretty fast. I think it’s healthy to treat design docs like a historical artifact - true at one point in time. It’s less likely they stay up to date to reflect reality.

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