Is documentation a dirty word?

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.

 

Research into how API documentation fails

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:

How API documentation fails

How API documentation can be effective and useful

Do you know of any others?

A technical communication user’s hierarchy of needs

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.

content maturity model diagram

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”

Write and own your content, or someone will write and own it for you

Don't ignore your customers. flickr image by Ron PloofAdrian 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”

Webinar: Planning User Documentation When You Are a Startup Business

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”

Case study: Creating an easy to use Listener Guide for the Samaritans and the Prison Service

Through its Listener Scheme in prisons, Samaritans  provides  emotional support to prisoners who are struggling to cope, are self harming or are feeling suicidal.

Guidance for Samaritans volunteers that run and support Listener schemes was contained in a hard copy manual (the Guide to Prisons) which was cumbersome to update, difficult to navigate and not in a format that made it easy to share with prison staff. As a result, over the years, volunteers referred to it  less and less frequently meaning that consistency in delivery of the Listener scheme across the prison estate was being compromised.

Cherryleaf were tasked with converting the manual to a fully searchable, easy to use, online resource that would link to other relevant information on the Samaritans intranet and could also be made available on the Prison Service intranet. The new online Guide to the Listener scheme means that both Samaritans volunteers and prison staff have access to the same, up to date, comprehensive set of guidelines and information.

Maria Foster, Samaritans’ Prison Support Officer said:

“For Samaritans volunteers, having the information available on the intranet rather than in a manual in their branches, means they can find out what they need to know at any time; the search facility and page style ensures that information can be located and read quickly and easily.

For prison staff, this is the first time they will be able to see all of the Samaritans guidelines for running the Listener scheme; this will help to further develop their understanding of the scheme and will support them in facilitating the operation of the scheme in their prison.

Samaritans is delighted with the result of the project;

Cherryleaf understood the brief and very quickly got to grips with the subject matter, turning a cumbersome manual into a streamlined user friendly resource.”

 

The Samaritans provides confidential emotional support for people who are experiencing feelings of distress, despair or suicidal thoughts. You can talk to them, any time, on 08457 909090 (UK), 1850 60 90 90 (Republic of Ireland) or jo@samaritans.org .