We’re working on our latest online training course, which is about post-writing and revising technical documentation, and we’re looking for examples of bad content we can use for the course exercises. If you know of anything we could use, please let us know by email.
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.
There are user documentation projects where we are asked to write in American English instead of British English, and generally this is a pretty straightforward exercise for us. However, when I speak at conferences in the USA, delegates sometimes ask me afterwards what I meant by a particular expression. For example, I was recently asked what I meant by “round the houses” and “cheesed off“.
There are a large number of subtle differences between the two versions of English, which has led to a number of very interesting blogs on this subject. In particular, Dr. Lynne Murphy’s Separated by a common language and Professor Ben Yagoda’s Not One-Off Britishisms blogs provide a fascinating insight into how words and expressions gain popularity. The Language Log is another blog worth reading.
If the move to a more conversational approach to technical writing grows in popularity, we may see these differences becoming a bigger factor in localis(z)ing to American or British English.
Microsoft has announced the preview release of its documentation service, https://docs.microsoft.com, which currently provides content for its Enterprise Mobility products.
“We interviewed and surveyed hundreds of developers and IT Pros and sifted through your website feedback over the years on UserVoice. It was clear we needed to make a change and create a modern web experience for content…For years customers have told us to go beyond walls of text with feature-level content and help them implement solutions to their business problems.” (source)
The key features are:
- Improved readability
- “To improve content readability, we changed the site to have a set content width.”
- “We’ve also increased the font size for the left navigation and the text itself.”
- Including an estimated reading time
- Adding a publication date
- Improved navigation
- It is now based around sections on evaluating, getting started, planning, deploying, managing and troubleshooting
- Shortened article length per page
- Responsive Web Design
- Community contributions
- “Every article has an Edit button that takes you to the source Markdown file in GitHub, where you can easily submit a pull request to fix or improve content.”
- Feedback mechanisms
- To provide comments and annotations on all of the articles
- Friendly URLs
- Website theming
- You can change between a light and dark theme
Wow – this matches closely with the topics we cover in our Advanced technical writing & new trends in technical communication training course, where we look at the changes made by other organisations.
Although it doesn’t mention it in its announcement, Microsoft has also made changes to the style of its topic headings and content. There’s frequent use of words and phrases such as “protect”, “discover” and “understand and explore”.
We’ve yet to look at the site in detail, but initial impressions are very positive.
What do you think?
Yesterday, I wrote:
“There are some activities that seem like they always could be improved. One is creating an authoring environment where professional technical communicators and other staff can work together.”
Writing online Help is different from writing some other types of content, in that it involves topic-based authoring. Content is stored in modular, re-usable and flexible chunks of information. By moving away from a page-centric, document model, you’re able to organise and present published information in many different ways. However, it’s a different approach to what many non-professional Technical Authors are used to. Unfamiliarity with this content model, as well as the tools, can make collaboration difficult.
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.
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.