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.

 
QuestionImportance of Documentation Pin
Richard Andrew x6421-May-22 15:41
professionalRichard Andrew x6421-May-22 15:41 
AnswerRe: Importance of Documentation Pin
Mircea Neacsu21-May-22 16:41
mvaMircea Neacsu21-May-22 16:41 
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 
The heck... My initial reply here was for the thread above this one Unsure | :~

Anyway, I am one of those developers who does not write documentation (although I should).
However, what I'd like to see in documentation is:
- Where can I get the code?
- How can I run it locally for debugging purposes?
- How do I commit it to source control (dev branch, merge request, directly on main branch, etc.)?
- 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)?
- How can I deploy it to various environments (and what environments do we have)?
- Does it depend on any in-house packages and if yes, where can I find those packages and how do I update them?
- Do I need to know about any secrets, passwords, ID's, servers, etc.?

What I'd absolutely NOT want to see in documentation: how does the code work?
Code changes constantly, so I'd have to constantly change the documentation and I'd have to know where I should change the documentation, which is even harder than changing the code.
In code I can check where I use a certain variable, I can't do that in documentation.
So in order to update technical documentation I'd have to very carefully read it every time I change something (and I still wouldn't know if I missed something).
Any documentation I've ever read about code was outdated and did not reflect what the code actually did.
I can follow code using the debugger, so that's its own documentation and never lies to me.
A well-placed comment can work miracles there (like, I have one property that I cannot rename, I have two seemingly separate lines that should be executed in a certain order, and I have a use case for Thread.Sleep).

That said, I now have a client that has a small ASP WebForms layer that only puts records in a database.
The database is then read by some no-code background process.
For starters, I can't know which background process uses which tables without checking ALL background processes (which would take you some hours).
Every process is very hard to follow, has a lot of steps, and A LOT of tables, views and stored procedures.
It's mostly "read the data from some table (or view), send the data to a web API, store the results in yet another table, run a stored procedure that processes those results and puts them in a third table..."
I'm not sure documentation could fix it though Dead | X|
Documentation should never be a way to fix broken code (or no-code, in this case) or a broken architecture.

Documentation can be really useful for manual processes, like enabling a client or user to use OAuth in your application (if that's a use-case you have, of course).
More like a sort of internal FAQ, what should I do when a customer asks me to...?
That's more functional than technical documentation though.

Documentation has never been a reason for me to join or not join a company.
If a team of six developers can help me with any of the above questions that's almost as good as documentation (until all six decide to quit Wink | ;) ).

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 
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 

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   407 votes