The next advanced technical writing course will be on 23rd June

The next public Advanced technical writing & new trends in technical communication classroom course will be held on Thursday 23rd June, at our training centre in central London (WC2R). We’ll be updating the content from last month’s course, to reflect the recent and upcoming developments at Microsoft.

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

Microsoft has announced the preview release of its documentation service, https://docs.microsoft.com, 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?

The return of Clippy?

Are we seeing the the spiritual child of Clippy emerge? Truth Labs’s Stelios Constantinides has written an article on his experiments with conversational UIs.

Conversational user interfaces (CUIs) are a spoken or written way of interacting with a device. CUIs aren’t completely new, but they’re becoming smarter, more natural, and — therefore — more useful.

Here’s where CUIs come in: since users already spend so much time in apps like Slack, Facebook Messenger, and even plain-old email, why not integrate your app inside these platforms?

Microsoft ClippyConstantinides  looks at the design process of creating something that doesn’t come across as a robot, and isn’t as annoying as Microsoft Clippy.

This links in with Ann Rockley’s concept of Intelligent Content: “Content that’s structurally rich and semantically categorized and therefore automatically discoverable, reusable, reconfigurable, and adaptable.”

For conversational user interfaces to work well, they need to be automatically discoverable, adaptable and semantically categorized. Microsoft Clippy wasn’t, which is one of the reasons why it failed in its purpose.

It’s still unclear whether this will lead to content being seen as code, or stored in a semantically rich format and inside a content management system. Whichever way, it’s important to recognize that the conversational language is different from written language. We speak differently from the way we write, and this is reflected in how we use messaging apps and authoring tools. Conversations are typically a one-to-one form of communication.

With Siri, Google Voice and Cortana closed off to most developers, we’re likely to see conversational user interfaces developed as alternatives to these applications.

One school of thought is users will move away from searching using sentences, and, instead,  learn to type commands (they will write command line instructions). In other words, they will begin to think and type more like programmers. This is illustrated in the image below.

Slack command line

I wonder if this might be a bit optimistic. There are many people find Twitter too difficult to use, and I suspect it would take them a long time to adapt to this approach.


This topic is something we cover (albeit briefly) in our Advanced technical writing & new trends in technical communication training course (the next one of which is on the 22nd of March).

See also:

(With thanks to Simon Bostock)

What do you think? Share your thoughts using the comment box below.

API documentation design patterns

One of the current developments in technical communication is the development of a common way to present API documentation. At present, there are a number of different design patterns that organisations are using, but, as with many things, there seems to be a desire to establish a de facto standard.

One part of this has been to establish the topics that should be covered in an API guide. Typically, this includes a conceptual overview, how to obtain authorisation keys, getting started and the important reference information of the endpoints, parameters code samples and error codes. The reference information includes having code samples that developers can copy and paste (and tweak to their situation). This often means different samples for each development environment.

The second part has been the the information design aspects of how the content should be presented. The Stripe API is one that probably has been copied the most. This organises the content into columns, with the code samples on the right side of the screen.

Last week, Tom Johnson tweeted about a new design pattern used by Lucybot:

This offers a console, accessible as a tab.

Lucybot example API Console2

This is quite an appealing approach because it could be replicated across a number of authoring tools.

The UK’s Government Digital Service is looking to establish a common standard for API documentation on the Gov.uk website, and this could have quite an influence on other sites looking for best practice to copy.

Which design patterns have you seen and liked? Share your thoughts using the comment box below.

Adapting to change in technical communication

Technical Authors work in a profession where they must be able to adapt to changes in the technology sector. Often, the changes relate to the outputs they need to create or the authoring tools they use, and most Technical Authors adapt quite easily to the new situations.

However, sometimes there are also changes to writing styles or the type of subject matter, and these can take a little while to get used to.

One significant development has been with the growth in Web-based, Software as a Service applications. In this environment, the User Assistance often fulfils a pre-sales and a training function, as well as providing the help when users get stuck. We’re working on a project at the moment where the writers have had to include this additional type of information, going against their natural inclination to be as succinct as possible. This has involved providing information on why you should use a particular feature, as well how to use it. For the writers, this have meant they’ve needed to gain a better understanding of the context in which the application is used, and deeper understanding of the users and their working day.

The other area that can cause challenges is writing API documentation. This is often written using different authoring tools than usual, and it often requires the writing of more factual, reference information. This can mean the writers need to have some understanding of the programming languages used to create an application, and be able to write for a more technical audience.

These differences is something I’ll be discussing in depth at the free Write the Docs London all day mini-conference on Friday, 4th March. In Aye, Aye, API – What makes Technical Communicators uneasy about API documentation, and what can we do about it?, we’ll look at the challenges mainstream Technical Authors face when writing API documentation.

If you have any insights or thoughts regarding the differences between writing end-user documentation and API documentation, please share them via the comments box below.

Five predictions for technical communication in 2016 and beyond

It’s not quite 2016 yet, but here are our five predictions for technical communication in 2016 and beyond.

Please note:

Here are our predictions:

1. As documentation becomes to be seen more as part of product design, so the technical writing process will become part of the product development process

We’re likely to see reviews and version control follow the developers processes, and be managed via tools such as Git.

2. Markdown will break out from being an authoring format for developers and into the mainstream

Markdown offers separation of look and feel, variables, topic-based authoring and single sourcing, in a tools-neutral, simple to use, format. At a push, you can also do conditional publishing, too (information typing is lacking, though). Because it is used by developers themselves, we’re likely to see the tools develop at a rapid pace, and become more powerful and easier to use.

3.  More technical communicators will use Lean methods when working in an Agile environment

Lean is something we’ve been discussing for a number of years, and seems to have picked up as a new topic at conferences recently.

4. We’ll see greater use of the imperative voice in topic titles

We explored this earlier in the year – The decline of the gerund in technical documentation?

5. The popular Help authoring tools will be able to generate embedded Help and on-boarding screens

This is more a wish, but it wouldn’t surprise us if the Help authoring tools will enable authors to single-source Help text that will be embedded in the UI itself or appear within on-boarding screens.

Your predictions?

Do you agree? What you see as future trends? Use the Comments box to let us know.

Cherryleaf’s Trends/Advanced Technical Writing Techniques – Next course 10th November 2015

Cherryleaf’s next Trends/Advanced Technical Writing Techniques course will be held on the 10th November 2015, at our training centre in central London (SW7).

This course is for you if you are an experienced technical communicator who wants to know about the current trends and ideas. Don’t get left behind: past clients include technical communicators from Citrix, GE, IBM UK, Lloyds Banking Group, Sage plc, Schlumberger, Tekla and Visa International.

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 stackoverflow.com 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