Microsoft launches its new documentation site, and it’s very good

Microsoft has announced the preview release of its documentation service,, which currently provides content for its Enterprise Mobility products.

“We interviewed and surveyed hundreds of developers and IT Pros and sifted through your website feedback over the years on UserVoice. It was clear we needed to make a change and create a modern web experience for content…For years customers have told us to go beyond walls of text with feature-level content and help them implement solutions to their business problems.” (source)

The key features are:

  • Improved readability
    • “To improve content readability, we changed the site to have a set content width.”
    • “We’ve also increased the font size for the left navigation and the text itself.”
  • Including an estimated reading time
  • Adding a publication date
  • Improved navigation
    • It is now based around sections on evaluating, getting started, planning, deploying, managing and troubleshooting
  • Shortened article length per page
  • Responsive Web Design
  • Community contributions
    • “Every article has an Edit button that takes you to the source Markdown file in GitHub, where you can easily submit a pull request to fix or improve content.”
  • Feedback mechanisms
    • To provide comments and annotations on all of the articles
  • Friendly URLs
  • Website theming
    • You can change between a light and dark theme

Wow – this matches closely with the topics we cover in our Advanced technical writing & new trends in technical communication training course, where we look at the changes made by other organisations.

Although it doesn’t mention it in its announcement, Microsoft has also made changes to the style of its topic headings and content. There’s frequent use of words and phrases such as “protect”, “discover” and “understand and explore”.

We’ve yet to look at the site in detail, but initial impressions are very positive.

What do you think?

Stack Overflow is moving into documentation (get the popcorn)

Stack Overflow, a collaboratively edited question and answer site for programmers, has announced its plans to add documentation to the site:

“Lately we’ve been asking ourselves “what else could we do to improve developers’ lives on the internet?”. Jeff’s original announcement of Stack Overflow said this:

There’s far too much great programming information trapped in forums, buried in online help, or hidden away in books that nobody buys any more. We’d like to unlock all that. Let’s create something that makes it easy to participate, and put it online in a form that is trivially easy to find.

Stack Overflow has made all of that a lot better, but there’s one area that is still hanging around: Documentation. Just like Q&A in 2008, Documentation in 2015 is something every developer needs regularly, and something that by most appearances stopped improving in 1996. We think, together, we can make it a lot better….

…We’re hoping we can improve documentation, not just move it under the domain.”

It will be fascinating to see how this project progresses – what issues they encounter, how they tackle these, and if the solutions work.

Continue reading

Atlassian no longer lets users comment on its documentation – good or bad news?

Last week, Atlassian sent out this message on Twitter:

This was a surprise, as Atlassian has been a strong advocate for having user comments appended to user documentation. Sarah Maddox, when she was working at Atlassian, posted the reasons why the company encouraged comments on her personal blog:

Continue reading

The conversation confusion in technical communication

Flickr CC image by Search Engine PeopleWe noticed last week a few tweets in our Twitter stream about how technical documentation and user assistance will be turning into a conversation.

A dictionary definition of conversation is:

1. The spoken exchange of thoughts, opinions, and feelings; talk.
2. An informal discussion.


Informal, verbal, interactive, spontaneous communication is quite different from pretty much all forms of User Assistance you’ll see today, so what do technical communicators mean by “conversation”?

Continue reading

What does Stack Overflow’s success mean for traditional User Assistance?

Last night, I saw Joel Spolsky speak at a London Enterprise Technology Meetup, held at the London School of Economics. Joel is one of the founders of Stack Overflow, a hugely popular question-and-answer website on the topic of computer programming. He also claimed in a blog post back in April 2000, no-one reads manuals (see our article If no-one reads the manual, then why bother?).

So I asked him about his thoughts on the relationship between question-and-answer sites like Stack Overflow and traditional user documentation.

Continue reading

Does relationship marketing mean you also need relationship content?

relationship poster Flickr image by TRF_Mr_HydeLast night I saw presentations at the Content Strategy London Meetup from Rob Hinchcliffe (a community strategist), and Sara Treewater (Content project lead for Citi Private Bank’s Web and Mobile team) in which they both mentioned relationship marketing and how it was influencing content strategy.

If your marketing and sales strategy focuses on developing a relationship with your customers and prospects, it makes sense your pre- and post- sales content (such as user documentation) sustains and builds relationships as well. Joe Gollner has called this “relationship content”. This may mean giving people an opportunity to comment, and supplement, your user documentation. In other words, moving from a monologue to a dialogue.

This can be challenging for organisations, particularly for those where there are compliance and regulatory considerations. However, there may be little choice but to do this. Rob Hinchcliffe said in his presentation that, today, content is everywhere. There are unofficial information sources where Google will direct users, if you do not provide content that’s relevant and useful.

If this relationship goes further, you can gain a significant insight into how each individual customer and prospect behaves, and start to disrupt your industry sector. We discuss this in our latest post on the STC’s Notebook blog (we’ll post a link once the post has been published).

New design models for providing end user Help

Ray Gallon has recently completed a series of webinars looking at new models for providing end user Help (A Cognitive Design for User Assistance).

In the third webinar, Ray looked at how people learn today and he suggested a new approach for the future. He used The Common European Framework of Reference for Language‘s description of people’s levels of competences to outline the different ways organisations help people to learn.
Continue reading

Education technology – Is this also the future for Technical Authors?

(Click on the image to enlarge)

Edudemic has created an infographic outlining the likely future for education. Other education sites, such as, suggest the future of study will have three main strands:

  • spend some time with experts
  • spend time on your own, and
  • spend time with your peers

If education follow this path, will this be true also for technical documentation and other forms of User Assistance? How will Technical Author adapt to these trends?