Click here to Skip to main content
15,504,424 members

Welcome to the Lounge

   

For discussing anything related to a software developer's life but is not for programming questions. Got a programming question?

The Lounge is rated Safe For Work. If you're about to post something inappropriate for a shared office environment, then don't post it. No ads, no abuse, and no programming questions. Trolling, (political, climate, religious or whatever) will result in your account being removed.

 
GeneralRe: Importance of Documentation Pin
Richard Andrew x6421-May-22 17:09
professionalRichard Andrew x6421-May-22 17:09 
GeneralRe: Importance of Documentation Pin
Mircea Neacsu21-May-22 17:37
mvaMircea Neacsu21-May-22 17:37 
AnswerRe: Importance of Documentation Pin
Jacquers21-May-22 20:27
Jacquers21-May-22 20:27 
AnswerRe: Importance of Documentation Pin
RickZeeland21-May-22 23:32
mveRickZeeland21-May-22 23:32 
AnswerRe: Importance of Documentation Pin
Daniel Pfeffer22-May-22 1:04
professionalDaniel Pfeffer22-May-22 1:04 
AnswerRe: Importance of Documentation Pin
Sander Rossel22-May-22 3:22
professionalSander Rossel22-May-22 3:22 
GeneralRe: Importance of Documentation Pin
Mircea Neacsu23-May-22 10:03
mvaMircea Neacsu23-May-22 10:03 
GeneralRe: Importance of Documentation Pin
Sander Rossel24-May-22 1:47
professionalSander Rossel24-May-22 1:47 
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 me, would be "to create a new account, find "accounts" in the menu and click on the plus icon ..."
That could be very useful to a developer when a user reports a bug in account creation, but usually you'd ask for steps to reproduce anyway Wink | ;)

AnswerRe: Importance of Documentation Pin
trønderen22-May-22 7:19
trønderen22-May-22 7:19 
AnswerRe: Importance of Documentation Pin
PhilipOakley22-May-22 23:36
professionalPhilipOakley22-May-22 23:36 
AnswerRe: Importance of Documentation Pin
Cpichols23-May-22 3:20
Cpichols23-May-22 3:20 
GeneralRe: Importance of Documentation Pin
MarkTJohnson23-May-22 3:52
professionalMarkTJohnson23-May-22 3:52 
GeneralRe: Importance of Documentation Pin
Cpichols23-May-22 4:03
Cpichols23-May-22 4:03 
AnswerRe: Importance of Documentation Pin
RussellT23-May-22 4:03
professionalRussellT23-May-22 4:03 
AnswerRe: Importance of Documentation Pin
Matt Bond23-May-22 6:28
Matt Bond23-May-22 6:28 
AnswerRe: Importance of Documentation Pin
NightPen23-May-22 6:43
NightPen23-May-22 6:43 
GeneralRe: Importance of Documentation Pin
RussellT23-May-22 12:33
professionalRussellT23-May-22 12:33 
GeneralRe: Importance of Documentation Pin
NightPen23-May-22 16:09
NightPen23-May-22 16:09 
AnswerRe: Importance of Documentation Pin
pmauriks23-May-22 19:24
pmauriks23-May-22 19:24 
GeneralHave a good funky weekend ;) Pin
0x01AA21-May-22 9:24
professional0x01AA21-May-22 9:24 
GeneralRe: Have a good funky weekend ;) Pin
Sander Rossel22-May-22 3:49
professionalSander Rossel22-May-22 3:49 
GeneralThe world's leading expert on European wasps walks into a record shop. Pin
OriginalGriff21-May-22 9:16
mveOriginalGriff21-May-22 9:16 
GeneralRe: The world's leading expert on European wasps walks into a record shop. Pin
Mike Hankey21-May-22 9:25
professionalMike Hankey21-May-22 9:25 
GeneralRe: The world's leading expert on European wasps walks into a record shop. Pin
Marc Clifton21-May-22 9:55
mvaMarc Clifton21-May-22 9:55 
GeneralRe: The world's leading expert on European wasps walks into a record shop. Pin
Mike Hankey21-May-22 10:03
professionalMike Hankey21-May-22 10:03 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.


Straw Poll

How would you describe your current job?
Fighting dragons everyday or clicking the same boxes on the same forms, day after day?
  Results   406 votes