4 ms·
Documentation is more like a pizza baking manual, so that if a new chef takes over, they can still make the same pizza.
by rzk 1y ago
Documentation is more like a pizza baking manual, so that if a new chef takes over, they can still make the same pizza.
- echelon_musk 1y agoA ... recipe?
- blueflow 1y agoExactly. Its knowledge transfer from the previous to the next generations. No knowledge transfer, so sustainable progress.
- WillAdams 1y agoRecording this sort of institutional knowledge is why I find it invaluable to write my code as a Literate Program: https://literateprogramming.com/ https://literateprogramming.com/ so that specific problems are documented.
- PaulHoule 1y agoSSL doesn't work with Firefox or Chrome. One could argue that no literate programming system has had more than one user. Knuth's WEB and CWEB never really caught on.
- WillAdams 1y agoGood point on SSL, should have used: http://literateprogramming.com/ http://literateprogramming.com/ Well, I worked up: https://github.com/WillAdams/gcodepreview/blob/main/literati.sty https://github.com/WillAdams/gcodepreview/blob/main/literati... for my current project (and will use it going forward for any new ones) and: https://github.com/topics/literate-programming https://github.com/topics/literate-programming has 443 projects...
- hk1337 1y agoThat's good but you still need documentation of available methods and how to use them. That's it's literate just makes it that much easier to connect what you read in the documentation with the code.
- PaulHoule 1y agoThat's one kind of documentation. Checklists and runbooks, for instance, are recipes. Other documentation describes APIs systematically (Javadoc) while other documentation describes architecture and broad concepts.