In August 2011, the entire Jira development team stopped work to take part in a furious flurry of screenshot-taking, gnashing of teeth and documentation updates!
I was sent to investigate this highly unusual behaviour. Why would self-respecting developers do this? Are they insane? More importantly, are they being recklessly abused by the Technical Writers as some kind of wildly inappropriate Mechanical Turk?
Interview 1: Giles Gaskell, Jira Technical Writer
Ed Dawson: Hi there Giles. What is a Doc Blitz?
Giles Gaskell: It’s basically a mass-screenshot-updating event. That’s really the main purpose of it. Undertaken by many participants, in this case the entire Jira development team.
ED: How did this concept come about?
GG: Originally, the Jira developers offered the Tech Writers some of their time to help update the Jira documentation, as a result of radical User Interface (UI) changes they were introducing into the Jira 4.4 Administration area.
ED: Have you ever done something like this before?
GG: No. It’s a first for us.
ED: How did you do it?
GG: Firstly, we came up with a plan to help us get the developers updating 200-odd screenshots in the Jira documentation. I created a planning page in Confluence (wiki), with a list of all the pages that needed updating. We showed a list of the images on each page, and divvied up the work based on the number of images. This event was purely to cover the Jira Administrator’s Guide, which was the documentation set most affected by these changes. For our “screenshotters”, we asked them to use Firefox 4 on a VMWare image running Windows 7 and take screenshots from a test Jira system hosted on our local network, which had sample data. We had some basic instructions on how to take the screenshots using specific tools and styles to ensure consistency.
As our screenshotters did the work, they updated our planning page, ticking off the items they had done. They could also add additional notes, for any items that were unusual or required further Tech Writer investigation. These notes were invaluable to Rosie (Greenhopper / Jira Technical Writer) and I when we proceeded to update the actual instructions and content around the new screenshots, as we asked the developers not to update the actual wording.
ED: How did you keep track of things once it was under way?
GG: During the event, I was monitoring the updates on the planning page and checking progress. At some point, someone created a Jira new project with a name that we couldn’t show in the screenshots, so I was able to catch that early. We gave the developers two hours, although most finished within one to one-and-a-half hours. When the blitz was over, we went through the planning page in detail, and ticked off each item, doing a sanity check of the images that had been uploaded. We did spend a lot of time updating the text as well, so it took some time to catch up on all of those changes. We rolled those updates into our regular documentation schedule and it took us (Technical Writers) about ten working days to update the rest of the admin guide. We had to re-do some of that work, because the UI changed again before the release.
In summary, the event was a complete success. It saved Rosie and me a heck of a lot of time and so we were very grateful to the developers for participating.
ED: Is this using developers as a Mechanical Turk to get things done?
GG: (laughs) If there are unscoped changes in a product, then yes! Actually, by and large the team were very apologetic and understanding about the changes as well.
ED: Do you have any plans do another ‘Doc Blitz’?
GG: Only if the UI changes a whole lot. We might do it again for Jira 5.0, if it looks significantly different. If the changes are subtle, then there’s no reason to use a process like this.
ED: Anything you would change if you ran another blitz?
GG: It would have been a good idea to run an IRC channel or other live chat room for the participants to be able to talk to the Tech Writers and ask questions.
ED: Giles, thank you for your time!
Interview 2: Matt Quail, Jira Architect
Ed Dawson: Have you ever done something like this before?
Matt Quail: No, not quite like this. Yeah, so updating all the screens, especially in documentation is usually something we offload to people other than developers at the end of the release.
ED: Exactly. So, how do you react to people saying that you’re basically being used like a Mechanical Turk to get this done?
MQ: I don’t think it’s like that at all. I think that level of documentation ownership is good to put back on developers, absolutely.
ED: If this is successful, would you take part again? How much time can you devote to this?
MQ: I think the time we can devote to this should be proportional to the number of changes we’ve been making. So, we re-wrote a lot or all of the UI for the admin (screens in Jira), so I think we have to take some of that on our shoulders. But the other thing is, we’ll probably automate it.
ED: I see!
MQ: Using our Ninja Coding Skills.
ED: All right, so watch this space, eh?
MQ: Yeah.
ED: Thanks for your time, Matt.
Interview 3: Andreas Knecht, Team Leader of the Jira “A-Team”.
Ed Dawson: What’s the A-Team?
Andreas Knecht: We’re one of the four sub-teams in the Jira team, we’re one of the UX (User Experience) teams, I guess.
ED: Right, and being the A-Team, obviously you’re the best team?
AK: That’s absolutely right, yes… 
ED: So you’re taking part in this Doc Blitz today. How did this come about?
AK: Well, essentially it was my team’s fault, we decided to re-write most of the Jira admin section, to improve navigation and the overall layout. But that meant that all of the screenshots in our docs were basically out of date, so we ended up having to re-screenshot all of them. So, Sharpie (Mike Sharp, Jira Design Engineer) on my team had the idea that we should do a blitz test, where everyone on the Jira team basically helps out and takes a few screenshots.
ED: Have you ever heard of something like this before?
AK: I don’t know, I don’t think so, I’m not sure if any other companies have done it.
ED: I think it’s a brand new thing.
AK: It could be, it could be, yes.
ED: Well thank you, and good luck with your blitz today.
Interview 4: Mike Sharp, Jira Design Engineer
Ed Dawson: Tell us about your creation of this “Doc Blitz” concept.
Mike Sharp: Well it seemed like a good idea, because basically with Jira 4.4, we’ve made massive changes to the admin section, which involves big UI (User Interface) changes. Which basically involves touching every single space in the admin (interface). So obviously, all our documentation, all the screen grabs and stuff, are out of date. Because there’s so many, it’s unfair to ask the Tech Writers to update them all on their own. So it seems fair to just do a bit of crowdsourcing within the Jira team, who are familiar with the product.
ED: And “Mechanical Turk” the problem.
MS: That’s right! (laughs)
ED: So the development team is on “code freeze” right now, so they have some time to do this. Having created a format for this work, could you repeat it again at the end of a sprint?
MS: In theory. I think it’s unlikely that we’re ever going to have this kind of level of changes to the actual look again, all in one hit.
ED: So this is more of a contingency where there’s dramatic UI changes.
MS: Yeah. So in the future, there’s probably ways that we can automate this. This sort of before-and-after screen grabbing. Where you can say “Okay, this has changed, re-do the screen grab, update the docs automatically”.
ED: How interesting. Well, we look forward to that! Thanks Mike.
