New voice, new tone, new IA: Writing for the modern developer
1. New voice, new tone, new Information
Architecture: Writing for the modern
developer
Keith Boyd
Senior Content Publishing Manager
Microsoft Corporation
2. 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
4. 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
5. The “Post-PC” era?
What to do? How can content strategy affect developer
sentiment and get devs to make a bet on Windows?
6. 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
8. The Evolution of Developer
Content at Microsoft
Dev Content 1.0
1980-1997
• It was a big book
• We literally printed it
• It was out of date before we
shipped it to customers
Dev Content 2.0
1997-2010
• Everything moved to the Web
• Semi-continuous publishing
• MSDN Library became the center
of gravity
9. 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
10. 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!‖
11. Windows 8 Dev Center Goals
• Clear, cohesive, easily understood value
One message proposition and step by step guidance
• Discoverable portal with SEO-optimized content
Easy to find and • Rationalized (and fewer) developer content sites
acquire • Coordinated content planning across MS teams
• How-tos/tutorials for Windows Store devs
Targeted • Great Getting Started experience
• Code samples and API ref for all Win8 languages
• Integrated with Windows Store and other portals
Integrated • Integrated with Visual Studio
• Integrated with key marketing messages
Supports Global • Globally inclusive, locally relevant
• Localized in key languages based on business
Ecosystem priorities
12. 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
13. Samples are the backbone of
the experience
Complex/
Large End to End Demos
• Inspire and motivate
Value
Prop
Cross-Feature Samples
Cross-Feature • Demonstrate advanced techniques
Guidance
API Feature Level Samples
• The building blocks
Feature Material
Code Snippets
Reference Material • Ease development and deployment
Simple/
Small
15. Windows Reimagined
Windows NT-Windows 7 Windows 8
Goals:
• Match the new friendlier personality of Windows
• Still be an authoritative source for developers
17. “Collegial, not colloquial”
Windows Developer Content Voice & Tone Principles:
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
18. Use simple tenses
• Before:
After a customer has paid for an app …
• After:
After a customer pays for an app …
19. 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.
20. 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.
21. 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.
22. Make the intro more casual
• Before:
The following steps describe the process in more
detail:
• After:
Here is the process:
23. 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.
24. 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.
25. 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.
26. 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.
27. 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.
33. 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