3 ms·
Documentation, while important is also a bit overrated in it's capabilities. Don't get me wrong - It would be lovely if you could simply read a bit of document
by pascalxus 9y ago
Documentation, while important is also a bit overrated in it's capabilities. Don't get me wrong - It would be lovely if you could simply read a bit of documentation to understand what's going on in the code. Reality is different. The details of understanding code, is in the code itself and how it connects to all the other bits of code.
The original author of the code has an understanding that far exceeds the explanatory powers of any documentation or anyone else that can come along and try to understand what's going on. By all means, attempt to document as much as you can, but don't expect it to be a silver bullet for understanding code.
- syshax 9y agoI wish more people understood this. There is no excuse to not have any documentation. One must always make an attempt to write a reasonable amount of documentation so there isn't a situation where there is no hope to understand anything except read all the source code. But a lot of people (managerial types especially) expect docs will be "step 1 look here, step 2 look there, step 3 fix with this exact command" Docs should explain how a system works, and perhaps some important places to look, but it's not a checklist to fix all problems. The consumer must still possess the ability, and will, to investigate and fix problems using their own critical thinking.
- chiph 9y agoAt a minimum, shops should have some short documents that explain where the code is in source control, what is needed to build it, where it got deployed, and some general idea about how to do a full system test. Call it the "Hit by a bus" doc if you want. Or more nicely -- the new hire orientation doc. And it's management's job to ensure it gets kept up to date. Because it's a business continuity issue.