Motivate Developers to Do Documentation Reviews Faster

Your Development works in Scrum, and you managed to become a part of those Scrum Dev teams instead of a waterfall-y, separated Documentation team that you were before. Yet, you’re still at the bottom of the food chain, and the Devs ignore your documentation tasks. I had a similar experience a while back. The interesting thing was that the Tour de France helped me. So, how to overcome this situation?

Image for post
Image for post

I became a Technical Writer in 2014 at a company called Kentico. This CMS vendor had already started with Scrum a couple of years before that, so I must admit that I came when the painful process was already done. The process for documentation tasks was pretty simple:

  1. The Product Manager defines a user story.
  2. Devs create and later program sub-tasks of the user story.
  3. Either Devs or I create its documentation sub-tasks for me.
  4. I process them.
  5. Devs do a review.
Image for post
Image for post
More detailed, yet still high-level look into the development process (in a BPMN-ish notation)

That all happens while I come to all Scrum meetings and participate in them. Usually, it meant that I had three to five tasks to do during a sprint for one team. After I got up to speed with sprints and the Dev team, though, I started to perceive a pattern I didn’t like.

Last-Minute Reviews, the Culprit

When I sent a documentation task for a review, it often stayed on the Scrum board in the same column for most of the sprint. Devs left it there until the end of the sprint when they didn’t have any unclosed tasks of their own.

When they discovered something to change in the docs, it was too late for me to make the changes before the sprint review.

Later, during the sprint review, it was said that the sprint wasn’t finished as planned because of the documentation.

While it’s true technically, I would have enough time to finish it if they reviewed the task before.

Don’t take me wrong, I don’t blame them — I would do the same in their shoes — but it made my life harder at best.

Is It Really a Problem?

You might say, “But it makes sense that Devs do programming tasks first as they’re more important than documentation, tutorials, or any other education.” That’s a pretty common opinion. “Customers are buying our product, and without a product, you don’t have what you’re selling. You can’t sell just the services.”

You’ve got to start with the customer experience and work backwards for the technology. You can’t start with the technology and try to figure out where you’re going to try to sell it.

— Steve Jobs

Actually, the services are usually as important as the product itself. Can you imagine using your CRM without documentation or support? On the contrary, going to absurd dimensions, the higher the enterprise market you have your product on, the more consulting firms are providing just services without any product. Consultants, administrators, advisors, etc.

That’s because your customers purchased your product to get some experience and value, not to own your product. (Unless they’re software collectors…) You buy a car so that it can transport you among different locations, not to have it in your garage.

Would you buy a car if the brand didn’t have any service center around?

Retrospectives Come Handy

So you know that you’re in the right. But how to fight it? Pulling all-nighters before releases can work for a while but eventually turns out to be self-destructive.

Feedback the Hell Out of Them

The easiest thing you can do is explain it to the Devs during a retrospective. And until this pattern changes, repeat it, broken record style! Technical Writers I’ve known have usually had two problems with this.

Image for post
Image for post

First, Technical Writers have a lot of work to do and a lot of Dev teams to take care of, so coming to an hour-long retrospective is time-consuming. That’s why they skip team retrospectives and can’t present their case. To this problem, I’d say that stressing about finishing sprint every two weeks also takes time and is much worse mentally in the long term.

Second, Devs tend to have arguments on why that current way is the right approach. Or worse, they’re stubborn about it. Well, you can’t really be surprised by that. If someone else did a thing I need and I wouldn’t need to think about it, I’d also be happy with that current format.

You might feel unsure about how to start talking about this with Devs so that it doesn’t turn out in a hate session or an hour of one-sided discussion. In that case, using nonviolent communication can be an excellent way to approach this. In any way, I would advise you always prepare with the team’s Scrum Master, who should know the team personalities and recommend the appropriate style of debate to you.

The impact of such actions will be even more effective if you’re friends with the Devs. Generally, the better the relationship you have with them, the better the effect you’ll have talking to them. If you’re not as lucky as I was, the debate is going to be most probably more official, but that doesn’t mean it can’t bring success.

Gamifying the Reviews

Another way to increase the chance of success while also helping with team building is to gamify the whole process. Try to come up with something that will resonate with the team members. Create a contest of some sort. Give points for reviews and give them a plaque for the winner. Or are they foodies with different preferences? Say you’ll vote with the best reviewer before the next team lunch vote. The possibilities are endless.

Similar to my love letter to retrospectives a little above, my gamification idea originated at retrospectives. I wanted to praise those who reviewed the docs in time. So I’ve always put up a post-it note with that person’s name and thanked him or her. In my team, pretty much everyone liked games, especially board games.

Over time I thought that something more formalized could actually support the team spirit and even further support the review process. So I came up with Tour de Documentation (read in French), a small contest borrowing the name of the famous Tour de France.

What were the rules? Each review of a documentation sub-task is worth some points. If it’s done in 24 hours, the reviewer gets 3 points. If it’s done in 48 hours, they get 2 points. If it’s done, but later, they get 1 point. The points would multiply if I noted that in the task (for those super big tasks where the review takes forever). This motivated Devs to do reviews in general while nudging them to do the reviews as soon as possible.

Every sprint in our development was one stage of Tour de Documentation, and each stage had a couple of announced participants:

  • Stage winner — the one who scored the highest number of points in the given stage
  • Fighter of the day — not really sure if this exists officially in Tour de France, I just saw it in newspaper articles, but it was for a person who made a significant contribution or somehow made the contest more interesting in the given stage
  • Yellow jersey holder — the one who was winning after the given stage
Image for post
Image for post
Presentation for the retrospectives

Devs were also promised an unspecified gift for the winner, who would be announced after the end of development of the upcoming version (that happened once a year). Each retrospective, I had a designated slot where I could have announced the interim results after every sprint-o-stage. Later on, I started to prepare short PowerPoint presentations with lots of animations and funny pictures (basically all presentation anti-patterns). You can see it on the right (I just blurred the faces).

Image for post
Image for post
Yellow jersey for the winner

In the end, what started just a funny motivator turned out to be a thing everyone was looking forward to. The gift for the final winner? It just must have been a yellow jersey (well, T-Shirt in our case) with a cyclist going towards two computer screens where all the reviewed tasks were listed.

Besides that, we threw a teambuilding party that included a winner podium (that can be seen on one slide in the presentation as an illustrative picture for a bit).

In the last year of the competition, I awarded 343 points in total.

Cheer Up, the Change Is in Your Hands!

You might be deprived of your current situation or be worried that if the development process changes to Scrum, your position gets worse. A good thing about agile methods, though, is that you can agilely change them from within.

Retrospectives can be boring and useless to you, but only if you let them be like that. Give some effort into it and can be a useful motivation tool and also a teambuilding activity. So don’t hesitate to use retrospectives as much as you can and get the maximum from your cooperation with Developers.

Image for post
Image for post

Written by

Customer Education team leader, occasional blogger, a movie person, comfortable traveler. Find all my articles at nosek.net.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store