Recording from UAEurope 2017 conference.
With many software developers now spending their time developing APIs, there’s an increasing demand for API documentation writers.
It’s a fast changing field, with emerging information design patterns and authoring tools. It’s also different from end user documentation, and this means many Technical Communicators are uncertain if and how they should migrate to these roles.
- what is an API and what is API documentation?
- the role of an API documentation writer, and how it differs from mainstream Technical Author roles
- the skills you need as a writer of API documentation
- becoming an API documentation writer.
REST API documentation training course:
Daryl Colquhoun has written an article in tcWorld about the international standard ISO/IEC/IEEE 26512. He explained the standard is going to be revised and renamed: from “Systems and software engineering – Requirements for managers of user documentation” to “Systems and software engineering – Requirements for managers of information for users”.
The reason for this, he states, is because, in many parts of the world, the term “documentation” is associated with a printed manual only. The neutral term “information for users” refers to all types of content: Online help, audio, video, and Augmented Reality.
The problem with “information” is it can mean many things. Information for users could mean the weather forecast. We may well need to move away from the word documentation, but I’m not sure we’ve yet come up with a suitable alternative.
It’s a while since we covered policies and procedures writing, so just a quick post to say Cherryleaf helps companies document their procedures for dealing with, and recovering from, unexpected disasters. It also can include planning for contingencies, including events that might seem highly unlikely.
There isn’t a great deal of research into API documentation, and the factors that make API content good or bad. Here’s some of the papers we’ve found so far:
Do you know of any others?
At the TCUK 2015 conference, Rachel Johnston mentioned the idea of a content maturity model. We thought we’d take this idea and ask:
Could we develop a model that illustrates a hierarchy of needs for users of technical communication (and in particular, User Assistance)?
A model of what?
We suggest calling this model a technical communication user’s hierarchy of needs. This is because we’re considering the different points where a user interacts with technical communication content, the information they need, and value it gives to them.
It takes a similar approach to the content maturity model Rachel suggested (shown in the photo below), with the least mature organisations providing just the legal minimum, and most mature content systems contributing to branding and evangelism.
A user’s hierarchy of needs also enables us to compare this model to similar models from content marketing and product design. For example, the categories in our model’s hierarchy roughly correspond to Peter Morville’s “User Experience honeycomb”, as well as the key elements in product design.
Continue reading “A technical communication user’s hierarchy of needs”
Adrian Baniak has written an article (3 Ways to Engage with Today’s Empowered Consumer) about how brands can “cut through the clutter” and communicate with their customers and prospect. He states one of the key ways to do this is “Write Your Own Tale, Or Someone Else Will Do It First”.
This mantra was originally made by Lisa Shalett, a partner at Goldman Sachs, and the global head of brand marketing and digital strategy. Continue reading “Write and own your content, or someone will write and own it for you”
At some stage or another, a technical communicator is likely to have seen this image from Kathy Sierra:
Continue reading “The end of two-faced product documentation?”
In conjunction with The Society for Technical Communication, we’ll be presenting the webinar Planning User Documentation When You Are a Startup Business on Tuesday, 19th February.
In this presentation, we’ll look at how to plan a user documentation project when you’re working for a startup technology company. Working in this environment gives you the opportunity to work “from a clean sheet,” but it also has its own challenges of working in a dynamic and rapidly changing environment.
Continue reading “Webinar: Planning User Documentation When You Are a Startup Business”