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

Software companies are not selling boxes anymore

Wistia’s Chris Savage has written an article on how the company focuses on articulating its company vision to differentiate itself in a competitive marketplace.

In the article, he states:

“To buy software back in the day, you’d go to the store, buy a box, and bring it home. Inside of the box would be a shiny CD, which had your new program on it.

You’d install the program on your computer, and then you’d use it for a few years. When the next version came out, maybe you’d get a discount because you bought the previous version. If it had some good upgrades, you’d consider making a purchase.

That’s all changed.

Now when you’re buying software, you’re not getting a static product. You’re buying something that’s continually evolving and changing. At Wistia, like most SaaS companies today, we deploy fixes and improvements multiple times per day.

When we buy software today, we’re not just buying into the current benefits, features, and price. Instead, we’re making a bet on the product’s future.”

Customers expect a continuing relationship with companies. They expect the product to grow, to see an ecosystem to evolve. Interwoven into this, is the support they receive. They expect high quality information when they want to explore how to get more out of the product, or troubleshoot any issues. This means User Assistance, the online Help, must become part of the initial design, and part of the user experience. It can no longer be an afterthought bolted on once the product has been developed.

The decline of the gerund in technical documentation?

Louise Downe, who works at the UK’s Government Digital Service, wrote a blog post (Good services are verbs, bad services are nouns), where she stated:

“After several rounds of user testing, the Home Office changed the name of ‘Immigration Health Surcharge’ to ‘check if you need to pay towards your health care in the UK’ – a service that allows visitors to the UK to pay for the cost of healthcare.”

Screenshot of Home office page, where  Heading uses "create"

Continue reading

Trends in technical communication – the funny airline safety video

The airline safety video is about actions that could save your life, but it can be very dull and mundane if you’ve flown more than once. So airlines are using the third aspect in good design – emotion – to engage with their audience.

The latest video to follow this trend is from Delta Airlines:

Other examples are: