Microsoft publishes its REST API Design Guidelines

Microsoft has published  its REST API Design Guidelines to the API community.

Microsoft API guidelines sample

According to Gareth Jones, Principal API Architect, who announced its release:

“The effort got started from hearing two key points of feedback from customers:

It should be easier to get started with Microsoft APIs – Developers wanted to be able to run the curl tool against an API endpoint and get a human-readable result in just a few minutes

APIs for Microsoft cloud services should be consistent – Developers didn’t care that an API to work with an Azure virtual machine and an API to work with a user’s Office 365 documents were developed by different parts of the company, they were both from Microsoft and developers expected consistency

One of the goals of the effort was to find the right balance of detail in the guidelines. We wanted a document that sufficiently codified best practices, but was also approachable for individual contributor engineers and technical product/program managers.”

Microsoft is a member Open API Initiative, which has been spun out of Swagger.

According to Gareth Jones:

“These guidelines represent a multi-year, cross-company, collaborative process aggregating the collective experience of hundreds of engineers designing, operating, and running global scale cloud services from across Microsoft; and listening to feedback on our APIs from customers and partners.  We have attempted to incorporate those learnings along with industry best practices in the API space to create guidelines that API teams across Microsoft use on a daily basis.”

“It’s our hope that by contributing ours to the community conversation, we can add to the body of community knowledge and reusable content so that anyone can draw upon more collective knowledge when looking to set standards and guidelines within their organization.”


Writing troubleshooting topics

It’s a fair bet that the introduction of the new Troubleshooting information type into the DITA 1.3 technical authoring standard will affect how all Technical Authors write troubleshooting topics, regardless of whether they use DITA or not. That’s because the proposed elements for troubleshooting topics make good sense, and it offers a standardised approach to writing these types of topics.

According to the Oasis DITA standards committee,

Troubleshooting topics provide descriptions of and solutions or workarounds for problem situations that users might encounter. Users refer to troubleshooting information to understand what condition or event generated their problem situation and to find out what they need to do to recover from or work around a problem, or to prevent a recurrence of the problem.

The user would see a topic that looks roughly like this:
Continue reading “Writing troubleshooting topics”

Where do the new trends and ideas in technical communication come from?


Sometimes we hear Technical Authors complain that the Help Authoring Tool vendors are not innovative enough. We believe that’s an unfair criticism, and that it’s unrealistic to expect the vendors to lead changes in technical communication. The new trends and ideas in technical communication need to come from other places.

We have moved away from Microsoft defining the universally accepted standard for online Help and the Help Authoring Tool vendors working within this framework. With no dominant leader defining the future for User Assistance, making small incremental changes is a less riskier option for the vendors. It’s safer to implement an idea that been proven to work and has been accepted by the technical communications community, than trying to make a major change and hope everyone will adopt it.

So where else will we see new trends and ideas emerging? Does technical communication innovation happen in the same was as it does in science (often in waves of rapid revolution)? Is it like the fashion industry (where ideas from a few leaders in couture work their way down to everyday clothing)? Or is there some secret body that’s making the decisions in the shadows for everyone?

Continue reading “Where do the new trends and ideas in technical communication come from?”

Searching for key words and phrases in training videos – Adventures in media synchronization

One of the limitations of video-based information has been the difficulties for users in finding a particular piece of information in a video. Usually, they have to watch the whole video, or “peck and hunt” to get to the moment containing the information they were searching for.

As we’ve mentioned in previous posts, HTML5, an emerging Web standard, enables Technical Authors and courseware developers to synchronize different media. One application of this is enabling users to search a text for a key word and then start a video or audio at that point. Here is an example.

Searching for key word or phrase in a video - example

In addition to making it easier for users to search videos for the information they need, it will also mean the pages will be more likely to appear in the search engine rankings. In other words, there will be an SEO benefit as well.

Synchronizing text and video within Web pages will become a lot easier in November 2012, when we are likely to see the the introduction of authoring tools containing this functionality (at the moment you need to be familiar with HTML and JavaScript).

We believe this is an exciting development in the field of user assistance.

Writing clear policy documents

Clear policies and procedures can have a profound effect on any organisation; they ensure that people know what they are doing, systems work properly and the people within the organisation are confident that the information in the policies and procedures is accessible, easy to understand and current.

However, writing clear policy documents can be very difficult to do.

Before you can write a good policy, you need clear decisions on which to base your writing. If the organisation doesn’t have a clear sense of what it wants to do, you as the writer will be compromised – there is only so much you can do with confusing or incomplete information. Policymakers must agree on policy before you, the writer, can write the policies.

You must also decide on your audience – whom you are writing for. The answer is often, our policy is for everyone, they all need to read and understand it. However, this means you have to write a document that must address multiple audiences with different agendas.

The temptation is to write policy documents primarily for those who audit the policies, which means the documents are often written in the passive voice. The problem with that is it can cause  a reader to become a passive spectator – they don’t ‘get’ what they are expected to do. The rules here is simple:

  • Imagine the least experienced user and write for that person.
  • Write primarily for those who need to use or implement the information.

Policies and procedures should always accomplish something – never write a policy or procedure just because it seems like a good idea. Very often policies and procedures can be knee jerk reactions to an incident. Somebody makes a mistake and someone else says “we should put a policy in place in case it happens again”.

You need to be a ruthless editor to avoid repetition and confusion across a myriad of documents. Break information down into ‘chunks’ or ‘topics’, with each topic containing one subject with a specific purpose, and then refer to (or embed) that topic in the other documents.

We’ve been working on a project to simplify policy documents within an NHS Trust. It’s a challenge simplifying a set of complex interlocking documents, but the results can be striking – helping staff understand why they should do things in a certain way and what the organisation is aiming to achieve.

Tackling the challenge of writing sales proposals and RFQs

Standards and processes permeate nearly every area of business today. They enable management to control, direct and delegate, giving people the ability to focus attention on the more difficult issues the business faces. Processes drives predictability, consistency and efficiency.

Despite all these benefits, sales departments have been much slower to move down this path. Sales people usually baulk at the idea of processes, complaining that “form-filling gets in the way of actual selling”.

Yet, according to Dario Priolo and Bethany Schultz, from sales training company Miller Heiman,

Our research clearly shows that “Winning Sales Organizations” take a much more scientific approach to selling and sales management than others. While there will always be a certain art to selling, it’s an increasingly sophisticated business world…How much better would a CEO sleep at night if he knew his sales force had a consistent, professional approach to interacting with customers! An improvement in these factors helps drive revenue predictability, reduces cost of sales and increases sales force productivity—all critical business objectives.

Miller Heiman argues that a sales process can help sales people “sell more and sell faster”.

Any successful initiative must include tools to streamline the process and remove any barriers to change. In this context, it makes sense to streamline one of the most time consuming aspects of selling – responding to Request for Quotation and other forms of sales proposals.

As we mentioned in our post “Building intelligence into business documents“, it’s now possible to create a system that can build the bulk of the document in a matter of minutes, leaving the writer with the task of customising the information to suit the requirements of each particular situation. These systems can even include training videos and text to guide a writer through the process of developing a new document, as well as enforce consistency and standards.

In the near future, we’ll be providing details on some the solutions available to organisations that want to improve the process of writing sales proposals and RFQs.