Re:The Surprising Power of Documentation
by Karrot_Kream on Monday June 12, 2023 @05:10AM
(#36290488)
Yeah this is why I love literate programming. Being able to read a program with "narration" is so much nicer than just reading documentation piecemeal. Maintaining literate programs though is a quite difficult because you have to figure out where new code or changes fit in the overall narrative. I have a scraper I wrote in literate style and I only have to change it yearly. Each year I forget what I wrote and then I reread the program and make the necessary changes.
[ Parent
| on HN ]
Literate programming is great until your code base becomes unwieldy. Then you need a README.md file which acts like a pointer to the correct entry points.
Then as the code grows, you need to document the architecture, add small gotchas, etc.
At the end of the day, documentation wins.
I am very code literate, but depending on the size of the codebase and how much smoke and mirrors are used, I might take longer to grok how things are interconnected by reading the code than it would take me if someone gave an high level overview in a paragraph or two.