By Keith Boyd
During the development of Windows 8 and Windows 8.1, I had the privilege of managing a team of 40 talented writers who were responsible for documenting a brand-new app platform. The team was comprised of dedicated and innovative professionals, with many award winners and an average tenure of 12 years in our industry. While 40 people may sound like a luxurious staffing level, consider the backdrop:
- The team was also responsible for maintaining and improving a library of legacy Windows programming documentation, over 150,000 total content assets.
- No tools existed to autogenerate the API (application programming interfaces) reference documentation for the platform, so we had to build the tools ourselves.
- Unlike iOS or Android, the Windows team decided to support multiple app models for Windows 8: HTML5 with JavaScript, XAML with C#, VB, or C++, and DirectX using C++. This meant that that programming guidance had to be created in triplicate.
While the team was excited and motivated at the prospect of supporting Microsoft's new mobile computing strategy, it was apparent that we lacked the resources to do everything we would like. We adopted a triage strategy and decided to apply the most resources where they would have the biggest impact.
When Windows 8 launched on 26 October 2011, the content we shipped reflected this strategy, born of pragmatism and based on irrefutable data showing that not all content assets were used equally. While it didn't come natural to many of us, by the time we shipped the content we had become adept at saying no—to our partners, to our management, and even to ourselves. We'd also become much better at interpreting data, which enabled us to focus on creating the right content, as opposed to all of the content we could think of.
In order to put this in proper historical perspective, step back in time to 25 October 2001 and the launch of Windows XP. In that era, Microsoft invested more on developer documentation than it does today:
- It was before the advent of Web 2.0, and there were very few websites with guidance on how to build Windows applications, services, or drivers.
- As market forces affected the Windows business, the balance of personnel investment also changed. Technical documentation budgets are a relatively easy place to plunder in favor of development, test, or project management. A noteworthy detail is that managers have been somewhat complicit in the decline of the population, mostly due to our inability to demonstrate our impact via meaningful, objective data.
Microsoft launched Windows XP with a robust and able community of programming writers, who meticulously documented the behavior of every API in the platform. In those days, programming for Windows was hardly easy, but it was straightforward and well documented. You could literally get a book and learn everything you needed to know. Our technical documentation augmented the narrative, providing deep technical detail on the many APIs that comprised the platform, but it did little to tell a story of its own. Storytelling just wasn't necessary in that era; if you were a developer seeking to build commercial software at a global scale, you really only had one choice—Windows.
Thirteen years later, Windows 8 and 8.1 ushered in an entirely new development platform, one used to build apps for deployment via the Windows Store. It supported a new matrix of programming languages, as well as three distinctly different app models. This complex matrix, coupled with a radical, new user interface, meant my team had its work cut out for it.
To maximize our effectiveness, we adopted four principles to guide our decision making:
- Less is more
- Code first
- Embrace a modern voice and tone
- Be data driven
The remainder of the article describes how we interpreted these principles to the benefit of our customers.
Less Is More
We realized early on that we needed to better educate the developers creating Windows. At the time, the Windows team consisted of more than 6,000 engineers, most of whom were building new platform capabilities and features. At Microsoft, there's long been an expectation that feature teams work directly with a programming writer to define a document plan for each release. Historically this was a confederated effort, with writers and their immediate manager empowered to negotiate the right level of investment on a per-feature basis. Unfortunately, this yielded uneven results:
- Not all features are created equal. For example, an investment in documentation for printer manufacturers doesn't yield the same return on investment as documentation targeted to game developers.
- Nearly all writers had a tendency to say yes while negotiating with their feature team counterparts. Saying no could put relationships at risk and might even affect their performance evaluation (thankfully the performance evaluation system at Microsoft was recently replaced).
- Building documentation as a collection of disparate features failed to consider how developers actually consume our content, by creating complex scenarios that span multiple features.
As a result, we started doing more deliberate capacity planning, focusing on the highest-value developer scenarios. The documentation team partnered with key allies in customer-facing teams who helped with prioritization.
In this new planning regime, writers would present their milestone plan to the entire leadership team. When proposed work items didn't align with divisional priorities or support the key customer scenarios identified by our leadership team, we said no and pushed that work to our backlog. That way, content proposals that were “nice to have” never trumped those that were critical to our customer's success. And feature teams (who once dominated our planning) were relegated to an informed participant, no longer the primary deciders of how and what was documented.
Code First
It seems so obvious: creating code samples that augment the core documentation should be a big part of the programming-writer role. However, this is easier said than done, given the enormity of our responsibilities.
At the outset of Windows 8 development, we determined that building additional customer empathy by creating apps (just like they do) would be the best way to have a truly informed content strategy. And despite how obvious that sounds, this principle was the hardest to live up to. Despite the desire and ability of the team, finding the time to write code proved incredibly difficult. Recognizing this, the team did a hard stop one month prior to general availability of Windows 8 in order to build apps using only our documentation and samples. The goal was validation, and the effort yielded over 100 content bugs (generally gaps in coverage or confusing/ambiguous language in associated reference documentation). So while “code first” made for a powerful rallying cry, it also demonstrated how difficult it is to fully realize a strategy or vision. But we did it anyway, and our documentation was better for it.
Embrace a Modern Voice and Tone
We had two goals for the voice and tone for Windows 8 developer documentation:
- Match the new, friendlier personality of Windows
- Remain an authoritative source for developers
To support those goals, we adopted four voice principles to better support a more “modern” developer audience:
- Approachable. We're talking on your level, and we're here to help.
- Focused. We get to the point, fast.
- Honest. We acknowledge pain, frustration, and complexity when needed.
- Relevant. We're aware you work in a world that isn't defined by Microsoft.
These principles manifest in innumerable ways throughout our technical documentation, with simpler, more direct language (I coined the phrase “collegial, not colloquial” to describe our approach), greater use of graphics and video, and concise topics that focused on the how as opposed to the why. After all, very few developers choose to read our documentation—they generally consume it by necessity and only when they're stuck. Being mindful of their time and treating them with compassion and respect was a key goal for the team (see Figures 1 and 2).
Be Data Driven
In the early days of Windows 8 planning, we discovered something interesting: 10% of API reference topics accounted for 90+% of the page views. This pattern, which held universally across all supported programming models, clearly showed that APIs were not used equally. The following figure shows how this looks for the Windows Runtime documentation.
As you can see from Figure 3, the top 1% of topics (the horizontal axis) account for 50% of all page views across the entire portfolio (the vertical axis. The long tail begins at 10%, just like the model predicted (I suspect this model is true for other developer platforms, including iOS and Android). Some of the topics in the long tail are viewed less than a dozen times per month. Some of them don't get viewed at all. As a leadership team, we decided to invest most of our resources in the topics that comprised the “head” (top 1%) and the “neck” (the top 10%). There's simply insufficient ROI to invest heavily in topics in the long tail.
The Bottom Line
The turning point came when we finally confronted that we can't do it all. With a limited number of writers supporting an ever-expanding portfolio of content assets, taking on the right work, selectively saying no, and focusing on the highest-value scenarios helped us to better meet the needs of our developers.
Increased customer satisfaction, more comprehensive scenario-based guidance, and additional code samples lead to an expanding catalog of apps in the Windows Store.
Our new approach worked.
Keith Boyd is a 14-year veteran of the Microsoft Corporation. He recently joined the cloud and enterprise division as a principal director in the content services and international team managing a group of programming-writers focused on Microsoft Azure and Visual Studio. When he's not in Redmond, he's at home with his wife, Leslie, and their three boys: Aiden, Riley, and Drew.