Importance of Documentation
-
Can I respectfully disagree? First let's clarify what I call "documentation". There is no generic "documentation" but documentation for a certain purpose. To make an analogy with the auto industry, you have the user manual that you get with any new car, than you have a service manual that mechanics use and you have design documentation that stays in the factory. They are not interchangeable and none of them replaces the other ones. You don't want to look at the service manual when you buy a new car and the mechanic has no use for the users' manual (you'd hope he's seen that type of car before). And of course you don't get to see the design documentation that manufacturers guard jealously. Pretty much the same applies to software. I think the OP was talking about design documentation, or the lack of thereof. It should explain the whys and tell little about the hows. Presumably the purpose of the system and the design don't change that often as to make it constantly obsolete. What you seem to refer to, is what I call "user manual": how to get the code, where are the passwords and so on. These are the nitty-gritty details that are very helpful but don't explain why the system was designed in a certain way nor how it was implemented. Finally, for the "service manual", the one that explains how the design comes to life, comments are just perfect. They are right there on the shop floor when the mechanic needs to fix something and can be updated right away when something changes.
Mircea
It doesn't really sound like you're disagreeing, just explaining things differently, or thinking about other documentation. We're developers and I assume the documentation Richard is referring to is documentation for us, developers. I'm also assuming he's not talking about comments in code, because he'd call them comments and not documentation.
Mircea Neacsu wrote:
I think the OP was talking about design documentation, or the lack of thereof. It should explain the whys and tell little about the hows. Presumably the purpose of the system and the design don't change that often as to make it constantly obsolete.
That would be my following two points: - How does this application fit in the landscape (is it stand-alone, does it depend on other services, do other services depend on this one)? - Does it depend on any in-house packages and if yes, where can I find those packages and how do I update them? Those two points would also answer Richard's question of "[...] how it works, how the data flows through the different layers and what components do what." You're a bit more detailed, I think, wanting to know how an application is build in terms of interfaces, base classes, etc. which could be a useful addition if this isn't directly clear from the code. For example: "For process X we're using IImporters and every client has their own implementation of IImporter which can be found in ... and depends on ... and is chosen/instantiated as follows ..." Overall, I'm not very concerned with the why of the system. It's here and people use it for one reason or another, that's a given. Knowing globally what it does can help in finding and debugging functionality, but it's not a requirement. That changes when you're tasked with thinking about how to make the program better and more useful for your customers, but that's not usually the task of a programmer and I wouldn't want to find it in the documentation that's supposed to help me run, debug and change a system.
Mircea Neacsu wrote:
What you seem to refer to, is what I call "user manual": how to get the code, where are the passwords and so on. These are the nitty-gritty details that are very helpful but don't explain why the system was designed in a certain way nor how it was implemented.
Depends on your point of view. If a user asks for a user manual, they don't want the code and they're not even allowed to secrets. A software user manual, to
