Live data from Hacker News

Why programmers don’t write documentation

kislayverma.com

21–30 of 153 posts

Re: Why programmers don’t write documentation

#21
I often see peers struggle with writing documentation because they prioritize it as a separate task. For example they write all the code in a giant PR and then try to go back and write the documentation for everything at once. This creates a much larger more insurmountable seeming goal than if they had broken up the task and written the docs for each piece instead.

Another critical mistake is expecting devs to cover writing the documentation that explains the deep contextual intricacies of the business logic and reasoning for said logic. Big mistake. Your docs should cover the code and how it can be operated. Anything else is why we have project briefs, strategies and other documents and meetings.

So writing documentation isn’t hard. It’s just more and more devs are coming from a willy-nilly-web-search-when-you-think-of-it background with no formal organizational skills or experience.

Most of what is written in doc-blocks above your function should be generated. Everything else is operational information.

Re: Why programmers don’t write documentation

#22

It's not rewarded and recognized. Good software, bad doc is probably okay. Bad software, good doc is downright bad. Therefore, people/exec/management don't prioritize it. If it were to be compensated with 100k, you would get the best doc ever. We can't improve things if we don't incentivize. We don't incentivize because it's not that important.

What if we don’t incentivize and it’s important? Further, what if we can improve it without incentivizing? My teams code is very well documented because we encourage documentation during code review. No one gets a bonus for this, but it doesn’t matter because we care about our softwares quality.

Put another way, good software bad doc is a lot harder and more costly than good software good doc.

Re: Why programmers don’t write documentation

#23
I wrote a whole Twitter thread a while back on this very topic: https://twitter.com/alexpotato/status/1224309861304938496

The single biggest ROI I've seen on getting documentation written is to provide a template for developers to fill out.

Blank wiki pages are incredibly intimidating and developers can't always anticipate what people will want. Having a "madlib" style outline with things like:

- Where does this app run?

- How do you start it?

- Where are the logs?

- How do you common items X,Y,Z?

Takes your odds of documentation being written from near zero (in my experience) to at least 60%.

Re: Why programmers don’t write documentation

#25

I’m in games so the visual element often forces this, but I’ve moved our team to making a lot of video content, both for PRs and for much of our “documentation”. I’ve always preferred reading, and the trend to everything being on YouTube has driven me nuts, but I’m a convert to this method for a few reasons. First, it’s fast. I can sit down and make a deep dive video in 30 minutes and not have to sit around writing a…

Videos are also better at transfering tacit knowledge. Stuff like little habits and workarounds people have that are important but which they don't realize need to be communicated.

For example, creating a virtual environment for a python project instead of installing it globally. This is a crucial step for things to work well, but it's so common it might be left unstated.

Re: Why programmers don’t write documentation

#26
It's also generally useless.

If you're building an open source general purpose tool, or something else meant to be reusable and consumed by the general public then sure. But the vast majority of software we write has a very definite lifecycle of birth, maintenance, and death. For the most part, one team with continuous word of mouth knowledge transfer will be responsible for it. And by the time that team has moved on, the software itself will have outlived its' usefulness. In an agile environment like this, keeping any kind of documentation up to date to be meaningfully useful is almost impossible without a dedicated team member.

Re: Why programmers don’t write documentation

#27

It's also generally useless. If you're building an open source general purpose tool, or something else meant to be reusable and consumed by the general public then sure. But the vast majority of software we write has a very definite lifecycle of birth, maintenance, and death. For the most part, one team with continuous word of mouth knowledge transfer will be responsible for it. And by the time that team has moved on…

I find having a few notes on the intention of a section is the most helpful.

Re: Why programmers don’t write documentation

#28

It's also generally useless. If you're building an open source general purpose tool, or something else meant to be reusable and consumed by the general public then sure. But the vast majority of software we write has a very definite lifecycle of birth, maintenance, and death. For the most part, one team with continuous word of mouth knowledge transfer will be responsible for it. And by the time that team has moved on…

And a good set of unit tests can also cover what's the most useful, like edge cases, complex sequence, particular client flows, bug that actually happened in prod etc

Re: Why programmers don’t write documentation

#29
post #19
post #15

Earlier quoted context omitted.

It's not bs. They said should, not must. Yes there are trade offs with everything you do in IT, one of them is creating a shit place to work in the name of speed. It might work for a little while but eventually you're going to realize you're shitting where you eat.

This was my attitude as well for much of my career, and it was a mistake. The "correct" decision depends on the state of the business and your resources at the time. And nothing else.

I don't know why you're getting downvoted. Tech debt is a tool and I think it's absolutely fair to put the needs of the business before documentation, or even code quality to a certain extent. As long as developers and management are aware that isn't free, and the cost must be repaid, I think it's the right decision in many cases.

Re: Why programmers don’t write documentation

#30
post #8

> Writing is a tough, demanding task. It requires organizing our thoughts clearly, examining them critically, and expressing them clearly. While the expressing part can be simplified to some extent (depending on the quality of writing required), all three steps are taxing when done properly. Wow, almost sounds like some other aspect of a job a software engineer is required to do... > If a developer doesn’t write docu…

>> Not writing doesn’t block shipping (at least not right away).

>It should.

The rub is that it might not block what's currently being shipped. But that debt can come back to introduce headaches and delays for the next ship.

Post reply on HN