This week I was at DevOpsDays Minneapolis, which was an amazing, warm, and inclusive event. There were at least three open spaces on documentation, communication, and related problems, and I didn’t propose any of them!
Minneapolis DevOpsDays 2017 logo
The question the devops world keeps asking, over and over again is,
How do I get developers to write anything?
There aren’t a lot of easy answers for this.
The first one is that if you care about developer-produced documentation, you should hire for it. But almost always, the people hiring are not the same as the people feeling the pain of missing documentation, so that may not happen.
The second is that you should hire someone other than the developers to write, if that’s important to you. I’m going to mention that all the times I’ve interviewed at Google, it was to be as an internal systems writer, documenting how things in the company work for other people in the company. Big, smart, companies hire writers for internal documents. But that is a tough budgetary sell.
The third, partial, answer, is that you make it significantly easier for developers to write. You give them forms and templates to fill in instead of expecting them to invent documentation theory. You specifically allocate writing time that can’t be budged for “one more tweak to the feature”.
Here’s the key problem though:
No developer has ever been fired for lack of documentation.
No developer I know of has gotten a bonus for documentation.
There is no stick. There is no carrot. There are a lot of competing demands on a developer’s time. Why on earth would they go do something that is not in their core competency just because you want it?
My instinctive response, whenever my kids want something, is to say, “It’s good to want things.” I think that is the instinctive response of most developers who are asked to do extra work. It’s not malicious, it’s just true. There is no reason they should do it – they won’t lose their jobs, the way they might if they prioritized writing over code. They won’t derive any benefit except the long-term and intangible one of being asked fewer questions. If they like being the source of knowledge, they’d be giving that away. If they like coding, you’re asking them to do something other than what they want. There is no upside.
So knowing that, how can we encourage developers to write documentation that we need?
First, reward it. Give people prizes for writing docs, or for throwing away or revising old docs. This needs to be something outside their usual compensation structure. Gift cards, time off, merit badges, whatever would be meaningful to that person. Ask them. They know what rewards them, because they use it to reward themselves.
A variety of rewards
Second, require it. I don’t mean “You have to write some docs or I will, uh, be disappointed in you.” I mean “The presence of documentation is a quality gate and you cannot release without it.” I mean “QA is using your docs as the test story.”.
Companies are never altruistic, humans are never purely motivated. We need to accept this and stop expecting people to do extra work because it’s the right thing to do, and start making the work not-extra, and the reward tangible.
This post was originally published on heidiwaterhouse.com
Top comments (2)
The need for documentation is definitely very real, but making it part of the job description of the programmers isn't the best use of their time, nor the company's balance sheet which reimburses them for that time.
And I'm sure you've discovered many programmers aren't very good at explaining technical details well.
Teams should hire technical writers to write the internal documentation for the team and other stakeholders. The teams will save money and have better software and internal docs as a result.
I have been told off for flippant documentation. Flippant coding standards. But never for code that didn't do its job.
OK. Variables like "ButteredSconesForTea" or "foozwak" don't necessarily add to code legibility and maintainability, but when I have to teach or train users hands on, I've always been praised for my clarity. Shame it doesn't find its way to my code/documentation!