As part of the attempt to make technical writing similar to other professions, there have been a number of moves by different technical communication societies to introduce certification. This can be a good thing, but there are some dangers with it as well.
Certification usually involves some training and a test. Students can be accredited or certified as having reached a certain standard. This might lead, at some point in the future, to organisations only hiring certified Technical Authors, in the same way they might only hire certified accountants.
So what are the dangers?
One danger with testing is that you tend to test what’s easy to measure, rather than test the talents someone needs to have. For example, multiple choice questions are easy to mark, but they tend to only test someone’s knowledge. They can test if someone knows “which X does Y”, but they are less good at checking if someone is able to explain “how X”. This can lead to an over-emphasis on teaching topics like the legal requirements for documentation, rather than testing whether someone can actually write clearly and simply.
A second danger is assuming there is only one right way to write a user guide. Technical communication is still a relatively recent area of study. We should still be open to ideas, to challenge accepted practice, if user testing shows that method or belief to be wrong. We don’t want to be the like the Paris Salon, which refused to show impressionist works by Manet, Monet, Renoir, Degas and Whistler, because they didn’t meet their definition of good art.
Although it’s more labour-intensive, we should ask students to make something, and then measure that against a set of user acceptance criteria: can they find the information they need?; do they understand it?; is it accurate?; is it complete?; is it cohesive? etc.
Microsoft has released the latest edition of its writing style guidelines as a website:
“Welcome to the Microsoft Writing Style Guide, your guide to writing style and terminology for all communication—whether an app, a website, or a white paper. If you write about computer technology, this guide is for you.
Today, lots of people are called upon to write about technology. We need a simple, straightforward style guide that everyone can use, regardless of their role. And it needs to reflect Microsoft’s modern approach to voice and style: warm and relaxed, crisp and clear, and ready to lend a hand.
The Microsoft Writing Style Guide replaces the Microsoft Manual of Style, a respected source of editorial guidance for the tech community for more than 20 years. The style guide features updated direction and new guidance for subjects that weren’t around when the last edition released. But it’s also a reimagining of Microsoft style—a tool to help everyone write in a way that’s natural, simple, and clear.”
It’s available for anyone to use, especially Technical Authors.
See: Microsoft Writing Style Guide
At this month’s WriteTheDocs London meetup, Jim Fisher of Pusher presented a talk called “Don’t say Simply“. He talked about words, such as “simply”, that can seem innocuous when written in user documentation, but which show a lack of sympathy when read.
He showed how popular “simply” is with developer documentation writers, by showing the number of hits for that word in GitHub: 93 million! If you restrict the search to Markdown files (the file type on GitHub used mostly for documentation) , it’s 3,325,386 hits.
“Easy” and “easily” are also problematic, and overused: There are 4,127,104 Markdown pages on GitHub for “easy”, and 2,797,143 Markdown pages for “easily”.
The problem with “simply” and “easy” is that the related task or concept is unlikely to be always simple or easy when the reader needs to read the documentation.
These words are typically “banned” in the main technical writing style guides, but they could be appropriate in training or marketing material. In general, it’s best Technical Authors avoid them.
Here is a link to Jim’s slides: Don’t say “simply” (Write The Docs London, 2018-01-23).
In this podcast, we look at the job of a Technical Author/Technical Communicator, and how you can start your career.
It’s been a while since our last survey of technical communicator salaries. So we thought it was time we conducted a new one.
We have contracted with QuestionPro, an independent research firm, to field your confidential survey responses. All responses will remain confidential and secure.
The questions will help us learn if salary levels correlate to factors such as age, gender, education, or levels of seniority.
We’ll publish the results on this blog.
Please use this link to complete the online survey:
Take part in the Cherryleaf 2017 European salary survey
Adobe has officially released the Adobe Technical Communication Suite (2017 release) including the new 2017 releases for Adobe FrameMaker, FrameMaker Publishing Server (2017 release) and RoboHelp. It has also released the 2.0 Release of XML Documentation Add-On for Adobe Experience Manager.
There have been a lot of improvements to the usability of the applications, reducing the number clicks required to carry out tasks.
For both FrameMaker and RoboHelp, Adobe has continued its developments in publishing HTML 5 output and personalised Help content. RoboHelp has a new, frameless Responsive HTML5 layouts that offer more intuitive navigation, and the ability to filter content dynamically. There is also a significantly improved search, which now has autocomplete.
It’s good that Adobe has focused on improving the usability this time – for Technical Authors and for the end users. It must be tempting to keep adding more to an application, when the best gains can be from improving what already exists.
Technical Authors are normally seen as masters of writing user documentation, but their skills are not often applied to other areas of the business. For example, it’s usually the case our clients for software documentation are different from our procedures writing clients.
However, we’re currently working for a client where we began by editing a white paper, and this has led us on to other projects across departments. Work has included developing customer journey maps, a terminology database, as well as the online Help. The role is morphing into that of a content editor role: checking for consistency, spotting errors in marketing copy, rewriting copy, and so on.
So what is different? What has led to this wider scope? It may be due to us being recommended to them by word of mouth, and they had greater confidence in our abilities. It may be because they are a start up. It could be because many of the staff are not native English speakers.
We suspect it’s because the first project was the white paper. They had something that was very useful to them, for promoting the company. They also included us in their in-house chat system, which meant we could see other areas where they had issues with content. This led to us intervening more than usual, making suggestions in a proactive way. The growth of chat systems, such as Slack and Socialcast, within companies could open up other opportunities for other Technical Authors, as long as they take the initiative.
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.