We’ve made a few changes to our online training courses, to make it easier to order and understand. There are now just three online courses:
We’ve moved all the other courses we had previously into a single, advanced technical communication skills course. The advanced course contains ten online modules in technical communication, and also it replaces our WriteLessons bundle.
The end user documentation writing skills for developers course is a version of our Technical Author/technical writing course.
The Technical Author/technical writing course hasn’t changed, and the classroom courses also haven’t changed.
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 researching what developers wanted to learn about writing documentation for users, the most common issue related to how much, or how little, they should write. One developer said:
“I would want to know what is the minimum I should write. If you can persuade me what is the necessity of each thing I’m capturing, and the voice I should use to make it most acceptable, I think I’d tune in.”
We’ll look at this question in the Writing Skills for Developers course, which we will be releasing soon. In general, you need to:
- Meet the legal requirements (which differ depending on the product, and the country).
- Provide enough information so that users don’t give up using your product, if they get stuck. For example, how to install the software, and how to get started.
- Consider the support calls, and whether you could avoid any of those by having good user documentation.
That might appear a bit too vague, so let me go back to one of the sentences above:
“If you can persuade me what is the necessity of each thing I’m capturing”
Before you start writing, you should define the purpose and audience for each deliverable you create. There should be a use case:
- Without documentation, is it clear what the user should be doing? is it clear what the user should be doing first?
- Is it clear how they should be doing the task?
- When they have to choose between options, do they have enough information to make the right decision?
- When they have completed a task, do they know what to do next?
- Are there any concepts or terms the user might not understand?
You can assess what topics to cover by doing some basic usability analysis. However, if you think about the tasks, the process (workflow), and any unfamiliar concepts, you will be on the right track.
Andrew Etter has written a short, Kindle ebook called “Modern Technical Writing: An Introduction to Software Documentation“. The book is Andrew’s personal view of technical communication, based on his experience of being a technical communicator in Silicon Valley.
It neatly describes the “Docs-like-code” approach to technical writing, and it challenges the impulse to write about everything. It describes Andrew’s experience of creating documentation in lightweight markup languages, such as ReStructured Text and Markdown, and using GitHub and static site generators to manage and publish the content.
Overall, I enjoyed reading the book. Andrew describes the benefits from following his approach. Ideally, I’d like to have seen more information and evidence to justify his opinions against other authoring tools. Microsoft Word might be a better choice than Markdown if you need to include complex images, tables or numbered lists. A Content Management System might be a better choice than a static website generator, if you want to provide intelligent content that modifies content to suit different users. The need to manage localised content (in multiple languages) might be easier to accomplish in DITA or MadCap Flare than by using GitHub and Markdown files.
Having said that, the book provides a useful insight into a increasingly common approach to documenting software applications.
I’ve been on the road speaking at a conference this week, and I’ve been listening to a lot of presentations on technical communication. Many of these were on the importance of having structured, semantic content when you are dealing with large amounts of content that needs to be translated into different languages and published in many different ways. All of these presentations put forward XML-based systems as the solution.
However, XML isn’t the only method for having semantic content. For example, AsciiDoc supports attributes, which can be used to add a semantic descriptions to headings, paragraphs and whole documents. You can use conditions in RoboHelp and Flare to categorise content. You can also store content in a database.
It’s sometimes useful to remember that XML isn’t the only way to semantic content.
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.
Randall 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?
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.