Can a Technical Author be a master of more than one trade?

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.

Adapting to change in technical communication

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.

Summary of the findings from our 2016 technical communications survey

We asked Technical Authors to complete a survey into the issues and challenges they face in 2016 and beyond. There were four main themes that stood out:

  1. Issues around working in an Agile environment.
  2. A need to develop skills in creating training screencasts. This included how to use tools, structuring and presenting content, and the ideal length of each video.
  3. Improving the status of Technical Authors and the Technical Publications department in the organisation. This topic has come up in previous surveys.
  4. Developing skills in using DITA.

We’ve looked at Agile recently, and we’ll revisit the other topics in the upcoming months.

Thanks to everyone who took part in the survey.

Revisiting “How many technical writers should we have in our organisation?”

We received an email today:

Having read your paper titled ‘How many technical writers should we have in our organisation?’,  I was wondering if you ever did the follow up the final results from you survey as mentioned in the paper and if they are available?

This refers to an article we wrote in 2003, where we looked at research on ‘standard’ ratios between developers and Technical Authors. We said we’d Cherryleaf would be producing a report on the final results from our survey this summer, but we didn’t obtain any new information that needed to be added to our preliminary report.

Have things changed since 2003?

There are some software tools for automating the creation of some API documentation, and organisations that have moved from Microsoft Word to a component-based content management system are likely to need to spend less time on the “look and feel” and formatting of the published content. However, we doubt these have had a major effect on the productivity of technical communicators.

An alternative way to determine the ratio

There is another way to look at the ratio of technical communicators to programmers – one we didn’t discuss in our original report. You could use the job sites to look at the total number of vacancies for programmers and the total number of technical communicators, and generate a rough-and-ready ratio that way.

It’s a rough estimate, because the job sites contain duplicate vacancies (a job can be advertised by more than one agency) and job titles can vary.

Looking at the reed.co.uk site today, there are currently 134 vacancies for Technical Authors and 761 vacancies for Programmers. That suggests a ratio of 17.6% , or roughly one in six technical communicators to programmers.

What do you think?

Please share your comments below.

The lone-liness of the UK Technical Author

We were looking at some of the survey results from the ISTC’s 2015 survey of technical communicators in the UK.

The survey reported:

  • 37.5% of the respondents worked as the sole technical communicator in their organisation.
  • 76% worked in an organisation with six technical communicators or fewer.

This means, in the UK, it’s harder to justify the ROI of large scale content management systems. With less content being created, the benefits may not outweigh the cost of the software. It also means that UK technical communicators need to rely more on resources outside their company if they want to develop with skills and keep up to date with trends.

The ISTC’s next survey is due for release in February 2016. We suspect we’ll find similar findings in that report.

The decline of the gerund in technical documentation?

Louise Downe, who works at the UK’s Government Digital Service, wrote a blog post (Good services are verbs, bad services are nouns), where she stated:

“After several rounds of user testing, the Home Office changed the name of ‘Immigration Health Surcharge’ to ‘check if you need to pay towards your health care in the UK’ – a service that allows visitors to the UK to pay for the cost of healthcare.”

Screenshot of Home office page, where  Heading uses "create"

Continue reading

What should be on our roadmap for training courses in technical communications?

We thought it would be useful to reflect on our plans for topics and courses in technical communications. In the past, some of the best suggestions have come from customers and prospects; it’s great to pick up useful ideas from others.

Today, you’ll find classroom or elearning training courses in:

We have a separate roadmap for business writing courses, which is where our policies and procedures training course (and again, Introduction to content strategy) fits in.

Our current thinking is to offer more topics around managing and planning technical documentation projects. In the past, we’ve offered an course on estimating projects. We also know managing project time is another important topic. Perhaps there are other topics that would fit under this category?

There’s also the issue of which courses should be online (recorded) courses, and which ones should be classroom-based (live) courses. Delegates say really like the two training venues we use in central London (we struck gold there), but online courses enable people to take a course pretty much anywhere and at any time.

If you have any thoughts, you can email us your thoughts, or you can use the comment box below.

What it’s like to be a Technical Author

We’re planning to carry out a number of videoed interviews with a range of Technical Authors this week. This is to help promote the profession. We’ll be asking questions such as what their role is inside their companies, and how they became a Technical Author.

The videos will be uploaded to the YouTube Channel for the Institute of Scientific and Technical Communicators, once we’ve edited and published them.