HACKER Q&A
📣 aromaticbanana

How do you motivate developers to write documentation?


I'm a junior developer currently working on a knowledge base for developers at the company I work at. I've set up most of the KB features but then it hit me:

Why would anyone use this?

There are countless other existing solutions that they're not using anyway, what makes mine different?

I've thought of focussing on the motive; to give the developer a reason to write documentation.

One the ideas was to have organizing workshops to be the center of the KB. Workshops would require research which would be the documentation. Past workshops could then be used to store related documentation.

What are other activities, interests that could motivate developers to write documentation?


  👤 karmakaze Accepted Answer ✓
> What are other activities, interests that could motivate developers to write documentation?

This is the wrong way of looking at it. It assumes a premise that documentation is a goal rather than a means.

To get developers to write documentation there's a few key ingredients. It has to deliver value that the writers appreciate. It has to keep delivering value over long time periods (e.g. stale docs can sometimes be worse than no docs). There has to be a culture/routine of writing documentation and kept as a priority so that it doesn't get cut when there's a time crunch or other work priorities. Oh yeah one other huge one is that it has to have minimal friction: e.g. commit it in the repo with the code changes so that it's no extra steps and the doc changes get reviewed with code changes.


👤 Leftium
I think documentation has to be tied to performance evaluation/salary, or at least not hinder your performance.

I worked at a large, well-known software company. There were very few comments documenting the code. Aside from the auto-generated comments based on function declarations, there wasn't much (any?) documentation.

I figured a big reason for this was people were paid/rewarded based on the number of bugs that they fixed, not on how much documentation was produced or other people helped.


👤 tomjen3
I am not a native English speaker, but even in my native language I am terrible at spelling. Somewhat better at grammar. However I feel that I was to write documentation for something I would just have a bunch of annoying nitpickers.

I would be far more willing to write documentation if it was for a pleasant to use wiki, where nothing was ever supposed to be finished, only improved: I would not feel pressure to be perfect, there would be no pressure to be complete (I can start out by just dumping my notes) I could get a nice dopamine hit by helping somebody.

I don't think a workshop would be helpful at all (is hurtful an English word?), not only would it be something that is not programming or being social (ie something that I would prefer not to attend), and I think you underestimate how much work there is in organizing it.


👤 pacifika
I write documentation to make onboarding easier.

End user documentation is usually written by developers to ease the support burden.


👤 patrick451
Just like comments, documentation is a code smell. Too much documentation is an indication that your codebase is in need of a major overhaul.