New voice, new tone, new IA: Writing for the modern developer
New voice, new tone, new InformationArchitecture: Writing for the moderndeveloper 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
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 developersentiment and get devs to make a bet on Windows?
Challenges facing the Windowsdeveloper 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
The Evolution of Developer Content at MicrosoftDev Content 1.01980-1997 • It was a big book • We literally printed it • It was out of date before we shipped it to customersDev 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 One message proposition and step by step guidance • Discoverable portal with SEO-optimized contentEasy 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 messagesSupports Global • Globally inclusive, locally relevant • Localized in key languages based on business Ecosystem priorities
The Windows 8 Dev CenterA 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 forumsContent 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 audienceInformation Architecture focused on a lightweight software developmentlifecycle: – 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 experienceComplex/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 deploymentSimple/Small
“Collegial, not colloquial”Windows Developer Content Voice & Tone Principles:Approachable• We’re talking on your level, and we’re here to helpFocused• Get to the point, and get to it fastHonest• We acknowledge pain, frustration, and complexity when neededRelevant• We’re aware you work in a world that isn’t defined by Microsoft
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 owncomponents, however, you must implement them asCOM objects.• After:But if you want to extend DirectShow by writing yourown components, you must implement them as COMobjects.
Simplify structure, vocabulary• Before:For example, a PCI bus driver might, in accordance with thePCI specification, replicate an I/O space resource in memoryspace.• After:For example, per the PCI specification, a PCI bus driver canreplicate an I/O space resource in memory space.
Simplify and use contractions• Before:Regardless of the reason why a site does not displayproperly when viewed in IE9 mode, we recommendthat you update the site to use techniques thatincorporate features from the latest standards.• After:If a site doesn’t display properly in IE9 mode, werecommend that you update it to use features from thelatest standards.
Make the intro more casual• Before:The following steps describe the process in moredetail:• After:Here is the process:
Start with a conjunction, remove unnecessary words• Before:Each major release of Internet Explorer adds features designed to makethe browser easier to use, to increase security, and to more closelysupport industry standards. As Internet Explorer gains features, there isa risk that older websites may not display correctly.• After:Each major release of Internet Explorer adds features to make thebrowser easier to use, to increase security, and to more closely supportindustry standards. But because of these features, older websites maynot 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 thatMessenger Connect will use to exchange tokens, data, and messageswith your application.• After:Your code must use this client ID (and sometimes the client secret) witha redirection domain, which is a domain that Messenger Connect usesto exchange tokens, data, and messages with your application.
Make the sentence more straightforward• Before:With Windows 8 you have a new opportunity to furtherdifferentiate your apps: deep links.• After:With Windows 8 you can further differentiate yourapps: use deep links.
Fix the focus• Before:Every app that you submit to the Windows Store goesthrough a Microsoft certification process.• After:Microsoft certifies every app before you can sell it inthe Windows Store.
Change to active, fix focus and vocabulary• Before:You can submit both Windows Store apps anddesktop apps to the Store, but only Windows Storeapps can be purchased there.• After:You can submit both Windows Store apps anddesktop apps to the Store, but you can sell onlyWindows Store apps there.
Communicate informally• Before:We wish you continued success in the WindowsStore.• After:Keep up the good work!
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