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