Technical content was a relatively easy place to plunder in favor of development, test, or PM resources
And they’d just as soon use non-authoritative resources on 3rd party sites like StackOverflow, esp. if the information is easier to consume or the content is easier to discover from search
Working with these constituent teams closely ensures tight alignment to strategy, making it easier to “pushback” against execs or others who want to dictate content strategy.
Goal: To inspire and motivate with useful, focused information that helps customers solve problems or create solutions quickly.
Went from 83 words to 40 words…narrowed to the intent of the topic to come up with a nice, clear abstract
Obviously critical APIs (ListView, etc.) got deeper docs for Day 1
Execs like innovation, customers value fundamentals. You have to deliver both!
Need to reboot your content creation strategy? Start with "No"
Need to Reboot Your
Content Creation Strategy?
Start with "No"
• 14 years at Microsoft, all in technical content.
• 12 years in management.
• 2000-2013 Windows writer and manager
• 2013-present Principal Director, Content
Services and International (CSI) in the Cloud
& Enterprise division (Azure, Visual Studio,
– Team owns roughly 10 million content assets as
well as the MSDN print and online magazine.
• Past-president, Western WA University
Staffing vs. platform growth
With each release of Windows, the
dev platform grew in size-- most
dramatically during Windows Vista
and Windows 8 development…
Programming-Writer population at Microsoft
… while staffing actually
*decreased*, somewhat dramatically
(values are approximate).
Why did staffing shift so
• Before 2005 there were very few sites
detailing how to build Windows apps,
services, or drivers.
• As market forces changed, the balance of
personnel investment also changed.
• Technical communicators failed to
consistently demonstrate their value relative
to other disciplines.
• Microsoft didn’t need scribes, it needed
Content innovation vs.
to be practical
for most teams
Untenable – no
team would accept
results at this level
Most content teams at
somewhere on the red
line, generally doing
or innovation well. No
suffered. What to do?
Win8: four principles
In order to maximize resources and
deliver greater value, we adopted four
1.Less is more
3.Embrace a modern voice and tone
4.Be data driven
PRINCIPLE: LESS IS
Too much content obfuscates and dilutes the
The painful truth…
3 primary reasons people come to MSDN:
1. To get the bits, or to provision an account.
2. To “Get Started” quickly with a product or service.
3. To get help when they’re stuck.
• Almost no one *wants* to read the content
that my team produces.
• And absolutely no one wants to read a 2000
word conceptual overview when they’re in the
middle of coding (much less a 100 page
Minimally viable content
• Historically, we tried to anticipate everything a dev might
need, and produced it.
• That lead to bloat, since content was created
speculatively; not based on articulated customer need.
• Ironically, right when we started to learn about how
customers were actually using our products, we shifted
attention to the next version, and began the speculative
cycle all over again.
For Windows 8, we built minimally viable content for use on
day 1, then paid closer attention to how customers actually
used our content so we could flesh it out later.
What is minimally viable
content for the dev audience?
• It covers all the basics:
– What the product is, and why you’d want it.
– How to acquire it.
– How to get started, quickly.
– API reference, at baseline standards of quality.
– Code samples for key APIs (not necessarily every API).
– Breadth information about the features that comprise the
product or service.
• What it’s not:
– A compendium of every imaginable scenario associated
with the product.
– An exhaustive, inclusive reference section with deep
– Comprehensive guidance detailing every feature in the
product or service. @Keith_Boyd #LavaCon
vNow vs. vNext
Adopting a “minimally
viable” approach lets
your team support users
while still building a
viable doc set for day 1
Keeping these forces in
balance is critical to our
content strategy – after
all, it’s the current
version of the platform or
service that actually
pays the bills.
With Windows 8, we centralized content
planning. We did this because…
– Not all features or scenarios are created equal.
– Not all writers (or leads!) are as good at
evaluating the relative value of investing in one
area against another.
– Nearly all writers said “yes” when negotiating with
their feature teams (the “scribe” mentality).
By doing this, we started every milestone
assuming that new content didn’t meet the bar
for inclusion (“No!”). Then we let the writer or
scenario owner talk the leadership team into it.
Well defined roles helped us work together more effectively to create better content
experiences across the customer’s journey.
Developer Evangelism & Support
Product Marketing Site Management
Key scenarios; campaigns;
premium content; SEM
Scenario flows; content
discoverability (SEO); metrics;
Content goals, plans and
scenarios; execution; IA
Customer advocacy; user
stories; competitive insights
Content teams at MS have been reluctant to embrace a
more “open” content platform. But times are changing:
• Resourcing constraints are forcing our hand.
• In the “real world”, software and content are
built side-by-side, in collaborative fashion
• Devs know more about their code than
In response, multiple initiatives
incent customer participation in
• Curah! curation platform.
• Soon: Collaborative documentation and better 1st and 3rd party community
When a developer is stuck, they don’t want to
read, they want code.
The leadership team recognized that the longer someone
worked at Microsoft, the less customer empathy they
exhibited. There are a number of reasons for that:
• Not enough hours in the day to continue to
“dabble” with the technology.
• Passion gets extinguished – “it’s just a job”.
• Loss of perspective due to assimilation into the
We gave writers so much to do that the skills and attributes
that made them such great hires in the first place slowly
withered away! How could we rekindle their passion?
Embracing code first…
Answer: write code. 25% of a writer’s total
capacity was reserved so they would:
• Gain firsthand knowledge of the platform,
from the developer’s perspective.
• Write more code snippets, which improved
the underlying reference content.
• Spend more time in small development
teams building end-to-end samples and
solutions (real world development)
• Test our content – when they were coding
and got stuck, the rule was they had to use
Benefits of Code first
• A happier and more productive team. Writing
code is fun!
• More complete and accurate documentation.
Bugs were filed when we found omissions or
• Deeper customer empathy. We developed
unique insights of value to peer teams.
• Additional end-to-end and feature level
samples. This raised our profile among the other
engineering teams and executives.
• Better content. We knew firsthand what content
devs needed to be successful, because we had
walked a mile in their shoes.
VOICE AND TONE
Acknowledge when things are hard, and
engage your customers in a more
humane, straightforward, and empathetic
“Plain English please!!!!”
Plain English instead of jargon from logic or math or whatever
that is write it in plain English and tell me why the copy
function does not work in this situation your language of
explaining is very difficult to understand in I plain am a business english!!!!
on an IT team, and I’m
Plain English would be great speak plain English offended as by we’re how
all geeks. Try plain English and only give me unfriendly the information your help is.
request. I need plain English with simple examples!!! Plain
English please. Plain English so us non comp literates can
understand. It was so over my head….geesh guys. Make it Plain
English. Tell me in plain
The Tao of Microsoft
“You’re trying to take something that
can be described in many, many
sentences and pages of prose, but
you can convert it into a couple lines
of poetry and you still get the
• Customer Intent. What are they really trying to do?
• Focus on the intent. Make the most common task
ridiculously easy to find.
• Easy to scan. Use formatting, art, headers, etc. to help
readers find what they are looking for.
•Write concisely. Try to cut the length by half.
•Word choice. Use everyday words. Use technical words
when they’re the right words.
• Read aloud. Give it a natural, efficient voice.
• Empathy. Acknowledge the reader’s situation.
• SEO: Assume they’re coming from search.
Traditionally, many web developers have
used browser detection in an attempt to
provide a consistent experience between
browsers. The typical implementation
performs a single comparison operation,
usually involving the user-agent string, and
then makes several design assumptions
about the features supported by that
browser. In practice, however, feature
detection has proven to be a more effective
technique that requires less maintenance.
This article shows how to use feature
detection to verify support for standards-based
features and demonstrates different
ways to detect features effectively. (83
Many web developers use browser detection to
determine what’s supported in a given browser.
However, feature detection has proven to be
more effective and requires less maintenance.
Let’s look at this in more detail, including how to
detect features effectively. (40 words)
knew that Steve
PRINCIPLE: BE DATA
There’s only so much quality content we can
produce. Produce the right resources; not
everything you can think of.
API Documentation at
API (Application Programming Interface) reference
documentation represents 80+% of the content produced and
maintained by my team. Why?
• Corporate and regulatory regimes designed to enable
• 30 years of Windows, and a commitment to backwards
• Ubiquitous market position that compels us to make our
products and services as flexible as possible.
While 80+% of our content is reference, every API isn’t created
The long tail…
Percentage of views
For Microsoft developer content projects, the top 1% of topics account
for 50% of all page views, while the top 10% account for 90+%. The
“long tail” starts after that. 90% of our content is hardly ever viewed!
The new approach
With Windows 8 RTM, we documented all APIs to
a minimally acceptable level of completeness.
• We then took the calculated risk to wait, to
determine which APIs were actually being used.
• To avoid small sample size, we reviewed data in
• By month two we had sufficient data to
determine which APIs were being used most.
Keeping a close eye on the data allowed us to say
“no” to unnecessary work.
Keeping an eye on the
Knowing where you stand relative to competitors is a
• We reviewed key competitor sites and
experiences in quarterly increments.
• Small teams scored each site across 30
• Ratings were inherently subjective, but normalized
at in-person discussions.
• We then reviewed our own site.
Key findings were cataloged, and shared with
partners. When executives or others asked “How
does Apple do that?” we had the answer.
• Don’t be a team of scribes. Be a team of SMEs.
• Keep innovation and fundamentals in balance.
• Remember that almost no one *wants* to consume technical content.
• Embrace minimally viable principles, then gather data and improve.
• Intentionally balance your investment between vNow and vNext.
• Hold a high bar for new work.
• Collaborate with related disciplines intentionally.
• Embrace outside help and curate where possible.
• Empathy drives SAT and helps your team anticipate customer needs.
• A great code sample is worth more than 1,000 words.
• Be concise, and write in plain English.
• Use data to invest in the right content, not everything you can think of.
• Knowing your competition gives you power – use it.
Connect with me!
• MSDN Magazine
• Twitter (@Keith_Boyd)
• LavaCon 2012 slides (New voice, new tone, new
IA: Writing for the modern developer)
• May 2014 issue of Intercom