3 ms·
>> enterprises would likely be better off with no documentation at all and just reading the source code. That, from the article, is quite a statement. Unsurpr
by hef19898 4y ago
>> enterprises would likely be better off with no documentation at all and just reading the source code.
That, from the article, is quite a statement. Unsurprisingly, no explanation is offered.
- paganel 4y agoNot the OP, but bad/not up-to-date documentation is worse than no documentation at all, as it might take you on the wrong paths while saying that that's the correct way to do it.
- skybrian 4y agoDocumentation that explains historical context is sometimes useful. The part that gets you is assuming it to be current. It might help to put dates on things?
- MattPalmer1086 4y agoDocumentation at a high level should exist as to what a system does and roughly how it works. Feature changes and so on need to be documented somewhere. The high level design aspects and change. Detailed documentation on software is a waste of time in my opinion. The software itself is indeed the best guide to how it actually works. Having no documentation at all is not good.
- awinter-py 4y agokeep the space shuttle flying, do not simplify this code
- MattPalmer1086 4y agoSafety critical systems is a whole discipline I'd love to know more about.
- awinter-py 4y agothat's a comment from the kubernetes codebase that has been at the center of 'docs vs self-document code vs linters' debates https://github.com/kubernetes/kubernetes/blob/ec2e767e59395376fa191d7c56a74f53936b7653/pkg/controller/volume/persistentvolume/pv_controller.go#L55 https://github.com/kubernetes/kubernetes/blob/ec2e767e593953... and strong agree, safety-critical code is fascinating; I mostly pick my tools for productivity, can't imagine how different my stack would be if it connected to dangerous equipment
- MattPalmer1086 4y agoDidnt know that, thanks! The comment in that code does a pretty good job of explaining why the code looks the way it does.
- conorcleary 4y agoYou've just volunteered to write the docs!
- hef19898 4y agoIn fact, I kind of did. Agile saved me from it. Like literally, I pointed out we need a comprehensive business requitemtns doc for a project. The answer was it will be covered under the individual user stories in Jira... Same for documentation, when you change the code, change the documentation.