Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Why programmers don’t write documentation

kislayverma.com

Post reply on HN
Print view View original

71–80 of 153 posts

Re: Why programmers don’t write documentation

#71

Post by xg15 »

> In the world of programming, where “it depends” is often the best answer and everything is based on trade-offs, writing becomes that much harder. It needs to set the context, justify the decisions, and then power the low-level thinking leading into the code.

Might be that the author is talking about a different kind of documentation, but I believe describing the behaviour of a program in sufficiently detailed fashion and justifying why the program behaves like it does are two very different things.

The former is the task of the programmer and the audience is likely other programmers while the latter is the task of a product manager and the audience is likely higher-ups.

As a programmer who needs to interface with a particular API, I will be very thankful for a documentation that tells me exactly how the data to pass to the endpoint has to look and what kind of responses I have to handle. If there are any particular quirks, constraints or special cases I have to be aware of when using the API, the documentation must explain those as well.

But to be able to use an API, it's not necessary to know the exact decisions and tradeoffs that explain why the quirks and special cases are as they are.

Re: Why programmers don’t write documentation

#72

Post by Nextgrid »

The problem with documentation is that the infrastructure/tooling for it is terrible compared to the infrastructure for code. Documentation is often in external systems (Confluence, etc) which lack version control and are hard to keep in sync with the code, and those systems are often extremely slow (especially considering all it does is handle text) and the user experience is terrible (no Markdown support, mandatory "wysiwyg" input, etc).

Re: Why programmers don’t write documentation

#73

Post by chaosite »

xg15 wrote: post #71

> In the world of programming, where “it depends” is often the best answer and everything is based on trade-offs, writing becomes that much harder. It needs to set the context, justify the decisions, and then power the low-level thinking leading into the code. Might be that the author is talking about a different kind of documentation, but I believe describing the behaviour of a program in sufficiently detailed fashi…

Programmers don't need documentation to describe what the program does, the code is already a perfect description of what it does.

You need documentation to describe the intent that is not present in the code, i.e., why something is the way it is.

Re: Why programmers don’t write documentation

#74

Post by noir_lord »

Nextgrid wrote: post #72

The problem with documentation is that the infrastructure/tooling for it is terrible compared to the infrastructure for code. Documentation is often in external systems (Confluence, etc) which lack version control and are hard to keep in sync with the code, and those systems are often extremely slow (especially considering all it does is handle text) and the user experience is terrible (no Markdown support, mandatory…

I just put a /docs directory in the root of the project and everything inside that is vanilla markdown.

It brings it under source control and if the person reading it doesn't know markdown they likely shouldn't be reading it anyway.

Re: Why programmers don’t write documentation

#75

Post by pdimitar »

It's bloody hard, you say? Hm, maybe in part of the cases, but you know what else is even harder?

Getting onboarded in a new project and having zero clue why X is written like that, why is Y is where it is and why Z is using a 10-year old thread-pool scheduler that is grossly inefficient. And you have to deliver feature A and bugfix B and you might collapse the house of cards and of course, critically important pieces of institutional knowledge are missing.

Eventually you do find out everything you need since you're not dumb and are a bright programmer, but you've lost weeks or maybe even months. The business have lost money because they basically had to give you anywhere from 1 to 3 full salaries just so you can catch up. And it's not even your fault, it's the last person's.

So I can't sympathize with "it's hard" at all. So what, dude? It's part of your job. Do it well. Nobody hired you to only do the easy stuff.

But this does outline the somewhat introverted, almost autistic nature of many programmers. When it comes to writing good docs most of them give up because that requires good and clear articulation which they don't possess. Or they find it "boring".

But they'd still curse if they found an obscure GitHub repo that could help with their their niche problem and find out that it has zero explanations or code comments.

Re: Why programmers don’t write documentation

#76

Post by hrbf »

kordlessagain wrote: post #56

I do both and it’s not hard, it’s work and people have gotten lazy and don’t do work anymore they just write and read BS on the net and call it true and vote people down for telling the truth.

So do I. I even write documentation for personal projects, as a manual to my future self. However, absolutely every team I've ever worked with held a majority view of documentation being unnecessary.

Some even mentioned "code as documentation". In the end, they just kept finding justifications for not writing documentation or even proper code comments.

Three months after some solution was written, they couldn't explain the thinking behind it or even all the deep dependencies and magic return values because the person who had written the solution had left the team. Even then they were unwilling to see how documentation would have helped.

This repeated with every freaking team I have ever worked with. The only documentation any of those projects had was the one I created while figuring out the code base.

I observed a fundamental laziness in written communication in many developers and to this day I find it puzzling. I sometimes write down a draft of some solution just by myself, like I would explain it to another developer. More often than not, this helps me in highlighting inconsistencies or errors in my thinking.

Re: Why programmers don’t write documentation

#77

Post by Nextgrid »

noir_lord wrote: post #74
Nextgrid wrote: post #72

The problem with documentation is that the infrastructure/tooling for it is terrible compared to the infrastructure for code. Documentation is often in external systems (Confluence, etc) which lack version control and are hard to keep in sync with the code, and those systems are often extremely slow (especially considering all it does is handle text) and the user experience is terrible (no Markdown support, mandatory…

I just put a /docs directory in the root of the project and everything inside that is vanilla markdown. It brings it under source control and if the person reading it doesn't know markdown they likely shouldn't be reading it anyway.

In all the places I've been that's now how things were and there wasn't any interest in changing it, so instead they kept going with a shitty and outdated Confluence/etc.

Re: Why programmers don’t write documentation

#78

Post by Corazoor »

kordlessagain wrote: post #56

I do both and it’s not hard, it’s work and people have gotten lazy and don’t do work anymore they just write and read BS on the net and call it true and vote people down for telling the truth.

I can agree that writing documentation is certainly more boring than writing code, and lazyness tends to play a role in the willingness to complete boring tasks.

But there are many legitimate reasons why one would clarify it as "harder" than programming:

- It requires a different skillset, namely writing.

- It is not uncommon for non-english shops to have a policy of documentation in english. That might be sensible, but complicates the task even further.

- In programming, it suffers from the same problems as math: Natural language is more often than not unsuited to express entirely abstract concepts, at least in concise and easily understandable ways.

- Conversely, natural language often lacks the necessary precision to talk about technical details.

- To alleviate all these problems with language somewhat, you might opt to use diagrams. Which requires yet another skillset.

- It requires time. And quite a lot of it actually. Usually more than you need for the actual programming task. This is why most managers care way less about documentation than they should: They know very well that it detracts time from actual programming tasks.

So sure, people tend to be lazy, but there are certainly good reasons why that happens more often in this area of our work than in others.

Re: Why programmers don’t write documentation

#79

Post by xg15 »

chaosite wrote: post #73
xg15 wrote: post #71

> In the world of programming, where “it depends” is often the best answer and everything is based on trade-offs, writing becomes that much harder. It needs to set the context, justify the decisions, and then power the low-level thinking leading into the code. Might be that the author is talking about a different kind of documentation, but I believe describing the behaviour of a program in sufficiently detailed fashi…

Programmers don't need documentation to describe what the program does, the code is already a perfect description of what it does. You need documentation to describe the intent that is not present in the code, i.e., why something is the way it is.

> the code is already a perfect description of what it does.

No it isn't.

Code is a series of steps that in the right environment will lead to a particular behaviour. Code doesn't (automatically) tell you what that behaviour is - even less if that behaviour is also the intended behaviour.

You can have "self-documenting code" to some extent, but even this code is often low-level, spread out over dozens of files and has to handle various cross-cutting concerns which are usually not of interest to you.

This is why command line tools have manpages, even if the audience are programmers and the code is open source, so a user could theoretically learn everything by looking through the code.

Re: Why programmers don’t write documentation

#80

Post by ChuckNorris89 »

pdimitar wrote: post #75

It's bloody hard, you say? Hm, maybe in part of the cases, but you know what else is even harder? Getting onboarded in a new project and having zero clue why X is written like that, why is Y is where it is and why Z is using a 10-year old thread-pool scheduler that is grossly inefficient. And you have to deliver feature A and bugfix B and you might collapse the house of cards and of course, critically important piece…

> critically important pieces of institutional knowledge are missing

And the guys who have it are the "10x devs" in that joint.

>Or they find it "boring".

Or, it doesn't count much towards your annual performance review so then why bother if you have enough stuff on your plate that does count towards your performance review.

When was the last time someone got promoted because they write really, really good internal documentation?

Let's face it, most web facing SW nowadays is like fast-food. Investing tons of time in writing quality documentation would by like a triple Michelin star chef writing a 20 page article about a doner kebab.

Post reply on HN