New voice, new tone, new Information Architecture: Writing for the modern developer

Keith Boyd

Senior Content Publishing Manager

Microsoft Corporation

About the speaker: Keith Boyd

• 13 year Microsoft veteran (today!). Entire MS career in Content Publishing discipline

• Manage a team of ~40 programming-writers & technical editors

• Team owns the technical/API documentation for nearly the entire Windows development surface, including Windows Store apps, Desktop apps, IE, and Windows Live; ~150k content assets that receive ~150 million views/year.

• http://dev.windows.com

THE CHANGING DEVELOPER LANDSCAPE

A brief timeline…

• 1992-2007: Only one major platform that enabled development and deployment of software at scale (Windows)

• 6/29/2007: iPhone released• 10/22/2008: First commercial Android devices• 3/12/2010: iPad available in US• 10/9/2012: There are now at least 3 platforms that

developers can choose to develop software at global scale – arguably more

The “Post-PC” era?

What to do? How can content strategy affect developer sentiment and get devs to make a bet on Windows?

Challenges facing the Windows developer content team circa 2009• People: do we have the right ones?• Publishing monoliths that hinder innovation• Outmoded POV on content creation - - “lather,

rinse, repeat” mentality. Little appetite for innovation• A crushing legacy of thousands of topics for legacy

platforms• “Silo’d” approach to documentation (feature-based)• A presentation and discovery model that was more

2000 than 2012

WINDOWS 8: A NEW APPROACH

The Evolution of Developer Content at Microsoft

Dev Content 1.01980-1997

• It was a big book• We literally printed it• It was out of date before we

shipped it to customers

Dev Content 2.01997-2010

• Everything moved to the Web• Semi-continuous publishing• MSDN Library became the center

of gravity

Developer Content 3.0: A Targeted, Integrated Experience

An experience that inspires and motivates devs to make a bet on Windows

Only the content that’s relevant to you – filter out the rest Content and samples that support end-to-end scenarios Content that facilitates and enables conversations. Create the

illusion of a dialog even when it’s really a one-way conversation Access to everything you need in one place. No more hunting

all over the web to find tools, SDKs, samples, etc. Friendly, conversational voice and tone – no more talking at

you. We’re talking with you and helping you understand the developer value prop and our POV on apps in addition to the technical aspects of our platform

Direct Quotes

• “The getting started/hello world experience is the most contiguous time I’ll ever spend in your docs—and it should be like 15 minutes.”

• “It really seems like you create content just for the sake of it.”

• “Your docs are speaking your org chart at me.”• “I hate videos.”• “More videos!”

Windows 8 Dev Center Goals

• Clear, cohesive, easily understood value proposition and step by step guidanceOne message

• Discoverable portal with SEO-optimized content

• Rationalized (and fewer) developer content sites

• Coordinated content planning across MS teams

Easy to find and acquire

• How-tos/tutorials for Windows Store devs• Great Getting Started experience• Code samples and API ref for all Win8

languages

Targeted

• Integrated with Windows Store and other portals

• Integrated with Visual Studio• Integrated with key marketing messages

Integrated

• Globally inclusive, locally relevant• Localized in key languages based on

business priorities

Supports Global

Ecosystem

The Windows 8 Dev Center

A unified, modern Windows developer portal (dev.windows.com):– Complete reference and conceptual documentation– An unprecedented catalog of online samples– Easy to acquire the developer tools and participate in community forums

Content that focuses on the how, not the why:– Consistent application of simplified content model– Focus on “How-To” and Quickstart topics (not DITA, but similar)– Getting Started docs that step through the basics in 30 minutes or less– Designers and creative directors are an important, addressable audience

Information Architecture focused on a lightweight software development lifecycle:

– Emphasis on building apps quickly, from Getting Started to Selling– Content organized by lifecycle: Planning, Designing, Developing, Testing, Selling– Deep conceptual topics buried a in separate node for architectural guidance

Samples are the backbone of the experience

Code Snippets• Ease development and deployment

API Feature Level Samples• The building blocks

Cross-Feature Samples• Demonstrate advanced techniques

End to End Demos• Inspire and motivate

Value Prop

Cross-FeatureGuidance

Feature Material

Reference Material

Complex/Large

Simple/Small

WINDOWS 8: NEW VOICE AND TONE

Windows Reimagined Windows NT-Windows 7 Windows 8

Goals:• Match the new friendlier personality of Windows• Still be an authoritative source for developers

MSTP?

“Collegial, not colloquial”

Approachable • We’re talking on your level, and we’re here to help

Focused • Get to the point, and get to it 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

Windows Developer Content Voice & Tone Principles:

Use simple tenses

• Before:After a customer has paid for an app …• After:After a customer pays for an app …

Fix unnatural sentence flow

• Before: If you want to extend DirectShow by writing your own components, however, you must implement them as COM objects.• After:But if you want to extend DirectShow by writing your own components, you must implement them as COM objects.

Simplify structure, vocabulary

• Before: For example, a PCI bus driver might, in accordance with the PCI specification, replicate an I/O space resource in memory space.• After:For example, per the PCI specification, a PCI bus driver can replicate an I/O space resource in memory space.

Simplify and use contractions

• Before:Regardless of the reason why a site does not display properly when viewed in IE9 mode, we recommend that you update the site to use techniques that incorporate features from the latest standards.• After:If a site doesn’t display properly in IE9 mode, we recommend that you update it to use features from the latest standards.

Make the intro more casual

• Before: The following steps describe the process in more detail:• After:Here is the process:

Start with a conjunction, remove unnecessary words

• Before: Each major release of Internet Explorer adds features designed to make the browser easier to use, to increase security, and to more closely support industry standards. As Internet Explorer gains features, there is a risk that older websites may not display correctly.

• After:Each major release of Internet Explorer adds features to make the browser easier to use, to increase security, and to more closely support industry standards. But because of these features, older websites may not display correctly.

Simplify vocabulary

• Before: Your code must use this client ID (and, in a few cases, the client secret) in conjunction with a redirection domain, which is a domain that Messenger Connect will use to exchange tokens, data, and messages with your application.

• After:Your code must use this client ID (and sometimes the client secret) with a redirection domain, which is a domain that Messenger Connect uses to exchange tokens, data, and messages with your application.

Make the sentence more straightforward

• Before: With Windows 8 you have a new opportunity to further differentiate your apps: deep links.• After:With Windows 8 you can further differentiate your apps: use deep links.

Fix the focus

• Before: Every app that you submit to the Windows Store goes through a Microsoft certification process.• After:Microsoft certifies every app before you can sell it in the Windows Store.

Change to active, fix focus and vocabulary

• Before: You can submit both Windows Store apps and desktop apps to the Store, but only Windows Store apps can be purchased there. • After:You can submit both Windows Store apps and desktop apps to the Store, but you can sell only Windows Store apps there.

Communicate informally

• Before:We wish you continued success in the Windows Store.• After:Keep up the good work!

WINDOWS 8: INFORMATION ARCHITECTURE

The lightweight SDL

Plan

Design

DevelopTest

SellVirtuous

cycle

Information Architecture in action

WINDOWS 8: BI & METRICS

Key Metrics

• Growth in Windows Store apps catalog• Growth in number of registered developers• Number of certified desktop apps• Year over year comparison: iOS and Android apps

vs Windows Store apps ecosystem growth• Page views/Site visits• Site experience SAT/Content SAT• Windows 8 global sales

QUESTIONS?