Why programmers don’t write documentation • Hacker News Board

Re: Why programmers don’t write documentation

#41

Post by akudha » Sat, May 01, 2021, 6:05 PM UTC

alexpotato wrote: post #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…

My manager uses a template to create JIRA tasks - it makes it short and to the point. Just a handful of questions like

Who needs it?

what needs to be done?

who is the subject matter expert?

and so on. This makes it easier for the developer working on the task, keeps the description short and sweet.

Re: Why programmers don’t write documentation

#42

Post by zabzonk » Sat, May 01, 2021, 6:06 PM UTC

29athrowaway wrote: post #20

Hire a technical writer. Not only for your external documentation... for all of it. If you are afraid of the costs, do the math. 1 technical writer for every 20 developers.

Now you have one more problem (several, in fact) - explaining the business and the software to the technical writer. This is so difficult, that in all my long career in software development and management, I never saw any company specifically hire a technical writer, though I have done a lot of technical writing myself, on the side.

Re: Why programmers don’t write documentation

#43

Post by dasil003 » Sat, May 01, 2021, 6:06 PM UTC

There's a common refrain that internal documentation never gets updated and so it's better to just look at the code. IMHO outdated docs are still better than no docs, you just have to approach them with an appropriate level of skepticism and archaeologist mindset. At the base level of course the code is the ultimate source of truth, and being able to navigate code history quickly (via something like the Fugitive vim plugin) is incredibly valuable, but higher levels of documentation such as code comments, commit messages, tech specs, product specs, and user documentation can give richer clues into the mindset of the team at the time. As such, I believe the single highest ROI thing you can do is to choose tools that automatically maintains history/edit timestamps for all docs (git obviously does this, but Google Docs and Quip also do quite well here).

Re: Why programmers don’t write documentation

#44

Post by FooBarWidget » Sat, May 01, 2021, 6:08 PM UTC

dasil003 wrote: post #43

There's a common refrain that internal documentation never gets updated and so it's better to just look at the code. IMHO outdated docs are still better than no docs, you just have to approach them with an appropriate level of skepticism and archaeologist mindset. At the base level of course the code is the ultimate source of truth, and being able to navigate code history quickly (via something like the Fugitive vim…

> you just have to approach them with an appropriate level of skepticism and archaeologist mindset

The problem is most people don't have this mindset. They expect documentation to be right, and when it isn't, they become frustrated and learn to avoid documentation.

Re: Why programmers don’t write documentation

#45

Post by freshair » Sat, May 01, 2021, 6:14 PM UTC

Because it's thankless. The bosses I've had generally seem to think that writing documentation beyond inline comments is a waste of time; something that shouldn't be done unless scheduled for. And of course it's always the first job to be postponed if the schedule is tight (it always is.)

At work, documentation gets written when the boss isn't looking. Corporate culture makes writing documentation taboo. The examples of great documentation I am most familiar with are written for open source projects where managers aren't around to hassle people for writing it. Particularly: mpv, ffmpeg, racket, emacs. In my career I have yet to encounter a commercial software project with documentation at this level.

Re: Why programmers don’t write documentation

#46

Post by alexpotato » Sat, May 01, 2021, 6:17 PM UTC

akudha wrote: post #41

alexpotato wrote: post #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…

My manager uses a template to create JIRA tasks - it makes it short and to the point. Just a handful of questions like Who needs it? what needs to be done? who is the subject matter expert? and so on. This makes it easier for the developer working on the task, keeps the description short and sweet.

A past manager of mine used to do the same thing but using templates for PRs (which is a great GitHub feature)

Re: Why programmers don’t write documentation

#47

Post by meowkit » Sat, May 01, 2021, 6:17 PM UTC

philosopher1234 wrote: post #22

ergocoder wrote: post #14

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.

As you say your documentation is a part of the code review process. Getting your (I assume) PR through is an incentive.

Totally agree with you otherwise.

Re: Why programmers don’t write documentation

#48

Post by MereInterest » Sat, May 01, 2021, 6:21 PM UTC

dasil003 wrote: post #43

There's a common refrain that internal documentation never gets updated and so it's better to just look at the code. IMHO outdated docs are still better than no docs, you just have to approach them with an appropriate level of skepticism and archaeologist mindset. At the base level of course the code is the ultimate source of truth, and being able to navigate code history quickly (via something like the Fugitive vim…

I think the big difference is what type of information you're looking for. The code is the final arbiter on what the program does, but gives incredibly little information about why it is designed that way.

* Can be learned from the code: Function A accepts a C-style pointer to a data array.

* Can be inferred from the code: Function A is called in an inner loop, and so it probably accepts that data array to avoid doing any memory allocation.

* Cannot be known from the code: Even though the data array is initialized to 0 in the current code, function A should not assume that will always be the case. That data array is intended to be used as persistent storage in a future version.

The first one is kind of pointless to document beyond what doxygen already gives you. The second is useful, but not necessary. The third is absolutely essential, because nothing in the current code can possibly tell you about the future intents for changes in the code.

Re: Why programmers don’t write documentation

#49

Post by watwut » Sat, May 01, 2021, 6:23 PM UTC

hesdeadjim wrote: post #6

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 super easy to produce. They are also wastful to watch and difficult to find something in.

So, our company creates videos, no one except new people watches them and everybody complains about lack of documentation.

Re: Why programmers don’t write documentation

#50

Post by watwut » Sat, May 01, 2021, 6:25 PM UTC

blunte wrote: post #9

Everywhere I’ve been except for IBM in the 90s, documentation is not given priority (time) as would be needed to both write the first round adequately and then maintain it as realities change. Tools are much less a problem. I suspect also that modern “agile” approaches work against building and maintaining documentation because developers are hyper focused on ticket level changes in short sprints. Same goes to a less…

Time is just excuse. I worked on multiple projects that had tons of time and very little or no time pressure.

People still did not liked writing documentation. They still did not knew how to write it.