Motivating Developers to Care About Documentation

getdx.com

16 points·nelsonmarcos··4 comments

It's not a matter of motivation. Programmers reduce the verbal understanding of their work to non-verbal symbolism. That's necessary to work efficiently in long complex projects where many ideas have to be manipulated. It is very distasteful to re-verbalize work that has been reduced to symbolism.

Lots of things might be thought of as "distasteful", but that doesn't mean one can't be motivated to do it. You might not like exercising, but there are still ways to be motivated to do so.

Saying that it's not a matter of motivation means what? We don't have devs treat documentation as important and give up? No, like other tasks that devs do, we set up a culture of positive feedback (it's not always money) for caring about docs.

> If you’re taking documentation really seriously, put it on the scorecard. Look for good writers. ... Then put it in your career ladders too. It’s a competency that individuals need to develop if they’re to move to the next level.

Exactly. If it's not evaluated and rewarded in the same way shipping code is (in hiring, too, as mentioned), it'll never be treated as important by developers. Devs are generally rational: if you say "write docs!", but then complain when things take longer because they were taking time to write docs, well, then you can guess what will happen.

IME the biggest killers of documentation are:

1) no time set aside to keep it up to date.

2) the tedium of reflecting changes made in one place in 3 others.

3) the fact that the MVP of a lot of organizations is the go to guy who can answer all the questions while amazing documentation is quickly taken for granted & rarely personalized.

Reply on news.ycombinator.com