Microsoft has released the latest edition of its writing style guidelines as a website:
“Welcome to the Microsoft Writing Style Guide, your guide to writing style and terminology for all communication—whether an app, a website, or a white paper. If you write about computer technology, this guide is for you.
Today, lots of people are called upon to write about technology. We need a simple, straightforward style guide that everyone can use, regardless of their role. And it needs to reflect Microsoft’s modern approach to voice and style: warm and relaxed, crisp and clear, and ready to lend a hand.
The Microsoft Writing Style Guide replaces the Microsoft Manual of Style, a respected source of editorial guidance for the tech community for more than 20 years. The style guide features updated direction and new guidance for subjects that weren’t around when the last edition released. But it’s also a reimagining of Microsoft style—a tool to help everyone write in a way that’s natural, simple, and clear.”
It’s available for anyone to use, especially Technical Authors.
See: Microsoft Writing Style Guide
Our client develops software to control machinery remotely, and it is looking for a contract Technical Author to assist in updating the online Help and user guides for its software. The contract is for 3 months, possibly extending month-by-month. Rate £36/hour.
See: #4182 Contract Technical Author, West Midlands, 3+ Months
Here are some more findings from our recent survey of European technical communicators. These relate to UK salaries. Most of the people who responded to our survey were based in the UK, so we are able to look at these in more detail than other countries.
We asked people to describe their seniority levels: Junior, Line staff/Standard, Senior/Team Lead, and Manager. These are often a key factor in the salary someone earns.
Excluding managers, the mean was £45,338.
Are the figures accurate?
The sample size was fairly small (n=61), so we do need to look at this information with some caution.
Data on the Technical Author salaries offered on the main IT jobs boards in the six months to August 2017 show a UK median annual salary of £50,000 (with a median of £47,000 for jobs offered outside of London). They also show a 25% increase in median salary offered (17.5% increase for jobs offered outside of London) since August 2016. That’s based on 167 job adverts – again a fairly small population. We also need to bear in mind the salaries in job vacancies can be higher than those for people who have been a job for a long time, and the number of Technical Author job adverts has decreased in the last 24 months.
See also : Cherryleaf’s recruitment service – Technical Authors and other content developer roles
Adobe has officially released the Adobe Technical Communication Suite (2017 release) including the new 2017 releases for Adobe FrameMaker, FrameMaker Publishing Server (2017 release) and RoboHelp. It has also released the 2.0 Release of XML Documentation Add-On for Adobe Experience Manager.
There have been a lot of improvements to the usability of the applications, reducing the number clicks required to carry out tasks.
For both FrameMaker and RoboHelp, Adobe has continued its developments in publishing HTML 5 output and personalised Help content. RoboHelp has a new, frameless Responsive HTML5 layouts that offer more intuitive navigation, and the ability to filter content dynamically. There is also a significantly improved search, which now has autocomplete.
It’s good that Adobe has focused on improving the usability this time – for Technical Authors and for the end users. It must be tempting to keep adding more to an application, when the best gains can be from improving what already exists.
Creating user documentation and online Help in a Continuous Integration/Continuous Delivery environment can be challenging for technical communicators and developers.
Continue reading “Creating documentation in a Continuous Integration/Continuous Delivery environment”
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 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:
- Issues around working in an Agile environment.
- 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.
- Improving the status of Technical Authors and the Technical Publications department in the organisation. This topic has come up in previous surveys.
- 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.
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.