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.

Explaining complicated stuff using simple words

Book coverRandall Munroe’s latest book Thing Explainer will be released tomorrow. In the book, Munroe uses line drawings and only the thousand most common words to provide simple explanations for complicated objects.

It’s good practice to use words that are commonly understood. In some industries, Technical Authors have to write using only a limited list of approved words  (a “controlled vocabulary”). For example, there are controlled vocabularies for aircraft maintenance manuals, because some maintenance engineers have a only limited amount of English.

Sometimes, the word “stuff” doesn’t help the reader to understand. So what do you do when readers need to understand the small differences between objects, particularly when they can have a big effect on what happens next?

XKCD cartoon

In order to write clearly, there are times when you need to use more than the thousand most common words. Technical Authors deal with this issue by using concept, terms and references topics. When they need to use words that some users might not understand, Technical Authors provide a link (or cross reference ) to another topic. This other topic provides an explanation or a definition of the word or concept. The topic can contain words, images, diagrams, animations or videos to help the user grasp the meaning.

It’s good to use simple words, but it’s more important to make sure the information is clear.

Do you need DITA?

Judging by Social Media last week, there were many strong opinions at the tekom tcworld conference towards the DITA authoring standard and the associated tools. It seemed, as the philosopher Swift once said, “Haters gonna hate”, and, by inference, “Hypers gonna hype”.

Eliot Kimber provided an interesting summary in a post to the DITA users group forum (Trip Report: Tekom 2015, DITA vs Walled Garden CCMS Systems):

“For background, Germany has had several SGML- and XML-based component content management system products available since the mid 90’s, of which Schema is probably the best known. These systems use their own XML models and are highly optimized for the needs of the German machinery industry…These products are widely deployed in Germany and other European countries. DITA poses a problem for these products to the degree that they are not  able to directly support DITA markup internally, for whatever reason, e.g., having been architected around a specific XML model such that supporting other models is difficult. So there is a clear and understandable tension between the vendors and happy users of these products and the adoption of DITA…
…It’s clear to me that DITA is gaining traction in Europe and, slowly, in Germany but that the DITA CCMS vendors will need to step up their game if they want to compete head-to-head against entrenched systems like Schema and Acolada. Likewise, the DITA community needs to do a better job of educating both tools vendors and potential DITA users if we expect them to be both accepting of DITA and successful in their attempts to implement and use it.”

This may have led those who are asking, do I need DITA?, to come away from the conference more confused than before. So, we thought it might be useful to provide a rough guide to whether it’s worth adopting DITA:

You probably don’t need DITA if:

  • The way the content looks to the user is the most important issue.
  • You have fewer than four writers.
  • You write narrative content.
  • You have limited budgets for tools, training and migration.
  • You don’t have the time to deal with the issues around changing working methods.
  • Your content has a “shelf life” of less than two years.
  • You use a lot of graphics with annotations.
  • You need to customise outputs [added] for individual documents [added] (such as PDFs).
  • The cost of migrating existing content will be expensive.
  • You want the presentation layer embedded with the content layer.
  • You don’t want to work within strict rules regarding how topics are written (where content is marked up semantically).
  • You need to put JavaScript code directly inside topics.
  • You need to use the tools used by developers or the marketing department.
  • You want a simple information architecture.

You might need DITA if:

  • You need to write to (and enforce) a standard.
  • You need to localise content into many languages.
  • You have more than four writers.
  • You want to write semantically.
  • You need a more efficient authoring, [added] reviewing [added] and publishing process.
  • You create many variations of the same document.
  • You want intelligent content that can adapt to different users and contexts.
  • You are spending too much time on formatting content.
  • You need to re-use content in different projects and different contexts, and make those topics accessible to other writing teams who might want to re-use them.
  • You need to establish a controlled vocabulary and taxonomy.
  • You want content validated for consistency.
  • You want automated publishing.

You probably do need DITA if:

  • You need to share content with other organisations.
  • Your content will need to last more than 30 years.
  • You want content to be stored in an open data standard, independent of any tool.
  • You don’t want to be tied into a specific authoring tool, content management system or publishing/rendering engine.
  • You need transclusion (where an element can replace itself with the content of a like element elsewhere) across a range of media.
  • You want to have a way of generalising back to a common standard.

 

Do you agree?

Please share your thoughts below.

Five predictions for technical communication in 2016 and beyond

It’s not quite 2016 yet, but here are our five predictions for technical communication in 2016 and beyond.

Please note:

Here are our predictions:

1. As documentation becomes to be seen more as part of product design, so the technical writing process will become part of the product development process

We’re likely to see reviews and version control follow the developers processes, and be managed via tools such as Git.

2. Markdown will break out from being an authoring format for developers and into the mainstream

Markdown offers separation of look and feel, variables, topic-based authoring and single sourcing, in a tools-neutral, simple to use, format. At a push, you can also do conditional publishing, too (information typing is lacking, though). Because it is used by developers themselves, we’re likely to see the tools develop at a rapid pace, and become more powerful and easier to use.

3.  More technical communicators will use Lean methods when working in an Agile environment

Lean is something we’ve been discussing for a number of years, and seems to have picked up as a new topic at conferences recently.

4. We’ll see greater use of the imperative voice in topic titles

We explored this earlier in the year – The decline of the gerund in technical documentation?

5. The popular Help authoring tools will be able to generate embedded Help and on-boarding screens

This is more a wish, but it wouldn’t surprise us if the Help authoring tools will enable authors to single-source Help text that will be embedded in the UI itself or appear within on-boarding screens.

Your predictions?

Do you agree? What you see as future trends? Use the Comments box to let us know.

Mankind – overcomplicating products for 1.8 million years

Olduvai stone chopping tool

In the radio series, A History of the World in 100 Objects, Neil MacGregor, Director of the British Museum, described the oldest man-made object in the museum – the Olduvai stone chopping tool. This was made approximately 1.8 million years ago in Tanzania, where the first humans originated.

MacGregor explained the tool has more than six chippings that sharpened this rock into a tool, when it only need two. He said:

“Those chips tell us that right from the beginning, we, unlike other animals, have wanted to make things more complicated than they need to be.”

Complexity, it appears, has been part of product design and manufacture right from the beginning. Did the need for user instructions follow shortly afterwards?

All our online courses – at a discounted, bundle price

You can now sign up for all of Cherryleaf’s popular online training courses at a discounted price!

This bundle provides you with access to:

By purchasing this bundle, you’ll save £180 ex VAT. That’s a discount of 38%.

See: Cherryleaf training course bundle – all our online courses at a discounted price