4 ms·
The post talks (mainly) about documenting code, but what I usually miss is documentation about the whole repo/project/service. For any piece of code, I can mana
by danwee 3y ago
The post talks (mainly) about documenting code, but what I usually miss is documentation about the whole repo/project/service. For any piece of code, I can manage to figure out what's going on (unless it's written in a way that's actually on purpose deceiving), but to understand how multiple modules work together (or why), to understand the purpose of the whole thing, that's rather difficult or impossible to know just by looking at the code.
So a big README.md file explaining the repo (why it exists, who are the interested parties, etc.) is better than the "little" documentation here and there about types, functions, examples, etc. Obviously I would love to have both, but the former is more useful than the latter imho.
- cWave 3y agoSomething like ARCHITECTURE.md? https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html
- madduci 3y agoIt only works in monorepos, what about distributed repositories/services then?
- sjaak 3y agoYou've already lost, best recourse in this case is to `rm -rf ~/repositories/`. Then make yourself a cup of tea, take a deep breath, and start over.
- madduci 3y agoand how do you manage the different lifecycle of services (versioning/build)?
- jalk 3y agoYou probably still have some entry point/example client that use those repos/services
- mike_hock 3y agoIf you make a separate repo for every five lines of code, you can make another one for the docs.
- eschneider 3y agoI usually add in: * How to build it * How to install it * How to run it * What other software or special hardware it needs You know, all the stuff I'll forget when I come back to the code after six months and would rather not have to figure out anew.
- timmb 3y agoDont forget: * What it does * What it's for
- eschneider 3y agoYes, that too. :) The point is to document the sorts of things you wish had been documented for you to orient yourself when you have to pick up a strange code base. Because that person is you in six months.