Last month, we were asked by a client to deliver our API documentation course to their team as a classroom course. Following on from that, we are now able to offer this one-day course to other companies, in this manner. The course currently varies from our online API documentation course. It includes more content on information design, and research into the different types of users and their needs.
Contact us to find out more.
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.
Happy New Year!
A quick update on the availability of places on our upcoming courses:
We will be scheduling another policies and procedures classroom course. This is likely to be held in February.
As a technical communicator, sometimes it can be hard to explain to others what it is you do. In the olden days, it was simpler: you could say you wrote manuals. Then, in more recent times, you could say you wrote online Help and manuals.
Today, there can be uncertainty of what is and isn’t technical communication. It can be unclear if certain deliverables should be created by a technical communicator or by someone else. For example, if content moves from a Help page to an onboarding screen, is it still technical communication? If the text moves into the interface, should the technical communicator create it? Are walkthrough videos a function of training or technical communication?
Continue reading “What is technical communication, actually?”
Here’s the latest Interview, with John McNamara of IBM, on what it’s like to be a technical communicator:
For the ISTC’s YouTube Channel, Ellis Pratt (Cherryleaf) is interviewing a number of technical communicators.
Here is Adrian Warman (IBM Cloudant):
Here is Brian Harris (Red Gate Software):
There’ll be more interviews in the coming weeks.
There’s an interesting discussion thread in the ISTC’s discussion forum regarding good and bad examples of technical writing. Incoming ISTC President Alison Peck has been asked by a researcher for a radio programme if she could provide some examples of technical writing: “well done, badly done and particularly innovative or strange”. As it’s a radio programme, these examples are likely to be read out.
This is not as straightforward to answer as you might think.
Firstly, most technical communicators work under non-disclosure agreements, so the best and worst examples often aren’t for public consumption.
Secondly, a lot of poor examples are from content that has been badly translated into English. They may have been well written originally, but they might have become mangled through the process of localising the content.
Thirdly, as Alison pointed out in her original message in the online forum, reading out very basic instructions out of context is not going to be particularly riveting or easy for the listener to grasp.
Fourthly, although technical communication is about clear communication – clear sentences – the role of technical communication is mostly about addressing the question, can the user do the task?
Minimalism, which most technical communicators use, focuses on:
- Adopting an action-oriented approach (to minimise the amount of reading)
- Starting immediately on meaningful tasks
- Supporting users in recognising errors and recovering from them
That requires more than clear and simple sentences; it requires information design as well. This means any examples ideally should show how well or badly they enable the user to complete the task. That requires an understanding of the task itself, and this makes it difficult to do this in a few seconds on the radio.
Since I wrote the post on Technical communication as a brand, we’ve been working on an idea we had for promoting the profession. The end result is another story, another free graphic novel you can download, called The CEO and the technical communicator.
It’s published under a Creative Commons licence, so anyone can forward it on, as long as they don’t modify it or sell it.
There’s a lot of factual evidence about the value of technical communicators to an organisation (such as the ROI calculators on our website), so we thought we’d see if we could appeal to the heart as well as the head by using a story-based approach.
Technical communication comes in many forms, so there were some challenges in coming up with something that was representative of the whole profession. Partly to get around this, the document shows people’s reactions to the content created, rather than showing the content itself. It also uses the word “content’ as a catch-all for document, manual, book, Help file, Web page, illustration, and so on.
We’ve also developed an ISTC-branded version that the Institute for Technical Communicators could use itself to promote the profession. We’ve sent it to to the ISTC Council for their consideration and comments. The document might be modified if they ask for any changes to be made; for example, we’re wondering if there should be greater emphasis on the writing aspect of the role.
You can download the Cherryleaf version from our website. Let us know what you think, using the comments below or by email.