We spotted an interesting statement by the “Father of Behaviour Design”, BJ Fogg:
“For somebody to do something – whether it’s buying a car, checking an email, or doing 20 press-ups – three things must happen at once.
The person must want to do it, they must be able to, and they must be prompted to do it.
A trigger – the prompt for the action – is effective only when the person is highly motivated, or the task is very easy. If the task is hard, people end up frustrated; if they’re not motivated, they get annoyed.”
See Ian Leslie’s article “The scientists who make apps addictive“.
If we want users to read Help text instead of calling the support line, then we maybe we need to meet those three criteria.
We can assume the user is motivated to fix their problem.
We can write instructions that are clear enough to make them able to solve the problem.
Where some applications fall down is they don’t prompt the user to read the online Help. The link to the Help text is often tucked away in the right hand corner of the screen.
Instead, we could put some of the Help text into the User Interface or the dialog screens, and we could prompt the user to follow a link to more information. Doing this could get users to read the online Help rather than call support.
At the Write The Docs event in London last night, Gergely Imreh presented Resin.io’s approach to customer-driven docs – documentation as self service support. Resin.io is a software company that provides Linux containers to the Internet of Things. It sees itself as a support-driven organisation, and so documentation is very important to them.
The discussions at the end of the talk were around which type of platform is best for developer documentation.
Resin.io uses an in-house system, based on Markdown and a flat-file publishing tool. They build pages from “partials” (snippets of re-usable chunks of information) to create “parametric information”. Pages can be built to match different criteria. For example, using Resin.io on a Raspberry Pi and Node.js. It provides an authoring environment that is easy for developers to use; it doesn’t require a database-driven CMS; and the content can be treated in a similar way to the code. The challenge with this type of system is getting it to scale. The “intelligence” of the system is through storing content in folders and using scripts within pages. As the grows, they are finding it harder to manage.
Gergely said he’d like see if a wiki-based system would work better. Content would be easier to edit, as pages would be more self-contained.
Kristof van Tomme suggested using a database-driven CMS. Pages would be built “on the fly”, by the CMS. In this situation, the “intelligence” of the system is through metadata wrapped around each topic and the database software that’s managing the content. The downside is it can mean there might be challenges in moving it to another platform at some stage in the future. You also have to manage the database and protect the CMS from potential hacking.
Another suggestion was to use a semantic language to write the content. This could be AsciiDoc or DITA. In this situation, the “intelligence” is placed in the topics and with the writers: they “markup” sentences or paragraphs for each applicable parameter, such as audience and computer. These can be published as flat files or be managed by a database. This approach is scalable and tools-independent, but it requires much more work by the writers.
What’s best depends partly on your view of the problem. Is it a information design problem, a software problem, or a data management problem? There are pros and cons to each approach.
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.
The Government Digital Service has been working on establishing a standard design for its technical (i.e. developer) documentation. This content is for systems architects, developers and users of the GOV.UK platforms and APIs.
You can see an example at: GOV.UK Platform as a Service
Cherryleaf was given a preview of the new design a few months ago, when we ran an API documentation training course at GDS. We made a couple of suggestions, which look like they’ve been included in the final design.
The documentation has these main sections:
- Overview. This includes why you would use it, and the pricing plan.
- Getting started. This includes prerequisites and limitations.
- How to deploy
- Managing apps
- Managing people
Elsewhere on the website is information relating to support, the product features, and the product roadmap.
As with other GOV.UK content, the team carried out research into what developers wanted, and they carried out usability testing. I understand the researchers discovered developers preferred content to be on a long, single page, and that they would be working in a two screen environment. Using long pages enables users to search and navigate with the keyboard, rather than the mouse. GDS also looked at other developer websites, such as WorldPay and Stripe, for best practice.
GDS is highly regarded in the technical communications community for its excellent work on the GOV.UK website. This means it is likely other organisations will copy GDS’s design for their own developer documentation.
Discover the advanced new writing styles emerging in technical communication by attending Cherryleaf’s popular training course. 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.
The next public classroom course will be held on Wednesday 29th March 2017 at our training centre in central London (WC2R).
For overseas clients, we will hold a class live over the web (on 22nd and 23rd March), if there sufficient interest.
Advanced technical writing & new trends in technical communication training
Industry 4.0 must be one of the “words of 2016′. We’re seeing a number of discussions on how this will impact on instructional design and User Assistance.
Ray Gallon has blogged on the question, what role should you have in machine-machine information?, exploring the differences between automatic, programmed dialogues, and non-programmed ones. Sarah O’Keefe has also blogged on the German initiative called iiRDS, the Intelligent Information Request and Delivery Standard.
It’s probably too early to form any firm conclusions on the impact Industry 4.0 will make, but it seems like some of the other trends we’ve highlighted this year are following a similar direction – documentation chatbots (docsbots), content as an API and treating documentation as code. There are similarities with iiRDS and APIs in looking at methods for content interchange, although it’s fair to ask, does the technical communication community need yet another standard?
On an API documentation course we ran for a client yesterday, we showed a number of developer documentation websites, including ones from Amazon, Dropbox, Google and Microsoft. One common theme the delegates noticed was these sites contained a in-page table of contents, or a set of related links, on the right hand set of the screen.
You will often hear Information Designers talk about F shaped reading, and that the right edge of the screen is ignored by users. If you put content there, they say, it probably won’t be seen by the readers.
So have Amazon, Dropbox, Google and Microsoft all got it wrong, by using the right edge of the screen to provide navigation? Have the improvements in screen technology and the introduction of tablets and smartphones changed which areas of the screen users notice?
What do you think?