Harnessing the power of the squad.
Abi Bettle-Shaffer, IBM Corporation

We got core developers to step out of their comfort zone and try something new. It saved our project time and money, and fostered better working relationships.

The Devs-in-Doc project was a homegrown initiative born out of necessity, that any team could use with minimal setup. We gave source access to our development teams, then gave them education so that they could make their own small changes, and free up the content developers to develop content.

Due to cuts in the writing team, each design hill in our product was left with only one writer, not only creating multiple single points of failure, but ensuring that if something did go wrong then there wasn’t an ounce of slack available to compensate for it. Add to that a clunky, painfully slow review process which would often see several days lapse before so much as a typo was fixed, and we had a recipe for a stressful, inefficient, and problem-prone documentation process.

Prior to the Devs-in-Doc project, the only way that internal developers, testers, and service personnel could review documentation was via a homegrown basic commenting system with the ability to respond to and close comments. In theory it was a simple, lightweight tool—in reality, commenters would often spend upwards of ten minutes leaving long, unclear footnotes which required more time to clarify and even longer to implement. Not to mention that work in this tool went untracked by the project. The time spent by writers and developers alike to address comments was invisible to iteration and project planning, silently eating into productive time and—with no proper tracking or prioritisation by a small, busy team—many comments went unaddressed for months at a time.

When the sunset of the old, already unsupported tool was announced, we​​ went looking for alternatives—and found them wanting. The tool that many other ID teams were banking on turned out to be even clunkier, and more importantly, far too heavyweight for our needs. Designed to provide a complete end-to-end review system, for us it would have duplicated function we already had from our source control and work flow management. So what now?

Devs-in-Doc was born. We had a complete work management system in our source code program—why not use it?—and anything considered too small to be worth the bother of opening a defect by definition didn’t require days or weeks of back and forth between writers and developers. We trusted the developers to write our code, surely we could trust them to fix a typo? With management backing, we opened the doors to collaboration, inviting the entire development team—typically only involved in the writing and testing of code—to engage with the documentation source. In doing so, we could better embed the documentation work into project planning, making it truly visible for the first time, as well as speed up the pace of delivery and review, mitigate those single points of failure, and improve understanding and team integration for everyone.

We began by identifying a couple of sponsor users and worked with them to understand what their expectations were, and then we threw them in the deep end. With the bare minimum of instruction, we asked them to deliver a change to the documentation, taking note of their questions and issues to build a one-page cheatsheet which would form the framework of the education to come.

Education was provided in small, informal groups. We provided everyone with the cheatsheet and off they went, asking questions and helping each other as necessary. By running these practical workshop sessions, we were able to deliver education face-to-face, and develop the supportive, self-organising environment we were aiming for right from the start.

By the end of a workshop, each participant had found the right file, opened it, spotted the (intentionally included, and often hilarious) mistake, corrected it, and delivered the change to the source. The education itself evolved as the process went on and we learned more about what the developers needed from us, and, more importantly, it gave them a chance to ask us why we were running the education. It provided us an opportunity to be transparent about tooling changes, the size of our team, and our motivations, and ensured that everyone was informed, and supportive, of the business case behind Devs-in-Doc.

Support was, and still is, provided by a dedicated Slack channel, as well as face-to-face troubleshooting when necessary, and not only from writers. More often than not, a question posted in the Slack channel is answered by another developer, speeding up feedback immensely.

In short our problem was, if not solved, significantly eased. Hill documentation is no longer at the mercy of a single writer: as evidenced by one team, who survived a product release without breaking a sweat, even though their writer was off for three weeks due to illness. Risks have been reduced, enabling shorter delivery cycles, sometimes as short as one day, instead of the few weeks that it used to be. Moreover, now that small changes and updates can be managed by developers as and when they spot them, we no longer accumulate as big a backlog of defects that need to be addressed before a GA.

More broadly, the project has seen great engagement with the documentation source from the product developers. We regularly see changes and review requests coming in from them, as well as a greater understanding of the work entailed in updating the documentation, which has improved awareness and collaboration on both sides of the proverbial fence. Almost immediately, one of our proactive developers began to actively help us clear the backlog of comments before the tool failed and evangelised to other developers about his positive experience. By doing this, we were able to turn the tool off ahead of schedule (see Figure 1).

Figure 1: Backlog numbers vs. developers involved in the project

It was only by embracing the agile notion of ‘fail fast, fail often’ that the Devs-in-Doc project was able to happen at all. Instead of agonising over the potential for error, we were able to get the initiative up and running in record time, with a minimum of prescribed processes to slow things down. Yes, introducing multiple new users to the source was likely to increase errors, but we were confident in our ability to handle those problems quickly, and make the most of them as education opportunities.

By encouraging an informal, supportive atmosphere, both writers and developers have enjoyed increased flexibility: developers no longer have to wade through the old, slow process to get changes implemented, and writers have more time to add value in places where their skills can be used to their full extent. One of the greatest, and somewhat unforeseen, benefits has been the increased communication between development and ID, and the sharing of expertise across the historical divide. Not only do the developers have a better understanding of the work involved in documentation, and how to do it well, but they’ve been able to provide the writing team with build and infrastructure expertise we simply hadn’t had before. In short: everybody wins.