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.

Our next advanced technical writing training course will be on 22nd March

We’ve just scheduled another of our Advanced technical writing & new trends in technical communication training courses.

“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.”

It will be held on 22nd March, in central London.

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.

Dates for our next advanced technical writing & new trends course

training room

Here are the dates for our next advanced technical writing & new trends course:

  • The next public classroom course will be held on 28th January 2016, at our training centre in central London (SW7).
  • A live Web course, for delegates based outside the UK, will be held on 6 & 7 January 2016 (2 x 3 hour sessions).

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.

See Advanced technical writing & new trends in technical communication training.

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

Using Markdown to create a boilerplate document for reports and proposals

Following on from our post Cutting and pasting content into Word documents – Is there a better way?, we’ve been looking at how organisations could use Markdown to create reports and proposals more quickly and consistently.

The objective was to:

  • Create something simple for non-technical people to use.
  • Have a collection of re-usable chunks of content that could be embedded into the document (no more cutting and pasting). If a chunk needed to be changed, then the documents where it is embedded would reflect that change automatically.
  • Be able to generate the completed report as a .docx (Microsoft Word) file.
  • Separate the content from the “look and feel”.
  • Enable different people to work on different sections of the document simultaneously.
  • Store the content in an open format, so there was potential to use some of the content in other places (such as on a website).

Continue reading

Stack Overflow is moving into documentation (get the popcorn)

Stack Overflow, a collaboratively edited question and answer site for programmers, has announced its plans to add documentation to the site:

“Lately we’ve been asking ourselves “what else could we do to improve developers’ lives on the internet?”. Jeff’s original announcement of Stack Overflow said this:

There’s far too much great programming information trapped in forums, buried in online help, or hidden away in books that nobody buys any more. We’d like to unlock all that. Let’s create something that makes it easy to participate, and put it online in a form that is trivially easy to find.

Stack Overflow has made all of that a lot better, but there’s one area that is still hanging around: Documentation. Just like Q&A in 2008, Documentation in 2015 is something every developer needs regularly, and something that by most appearances stopped improving in 1996. We think, together, we can make it a lot better….

…We’re hoping we can improve documentation, not just move it under the stackoverflow.com domain.”

It will be fascinating to see how this project progresses – what issues they encounter, how they tackle these, and if the solutions work.

Continue reading

New date for our advanced technical writing course

Trends in Technical Communication Course – Advanced Technical Writing TechniquesWe’re moving our public classroom course on Trends in Technical Communication Course – Advanced Technical Writing Techniques from the 18th September to Tuesday 22nd September. There are places available if you’d like to book.

We’ve also run this course a number of times during the summer as an “onsite” course for clients, using WebEx and Lync (soon to be called Skype for Business). Using online meeting technologies like these means we can deliver training to authoring teams throughout the world.

We have been asked if individual delegates overseas could use these platforms to participate in our public, classroom, course. I’m afraid we don’t offer this. The “online meeting” courses involve using special lighting and audio equipment that isn’t available in the training rooms we use for the public courses. Also, it would be very difficult for the trainer to manage two different delivery methods simultaneously.