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.
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.
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.
Technical Authors are normally seen as masters of writing user documentation, but their skills are not often applied to other areas of the business. For example, it’s usually the case our clients for software documentation are different from our procedures writing clients.
However, we’re currently working for a client where we began by editing a white paper, and this has led us on to other projects across departments. Work has included developing customer journey maps, a terminology database, as well as the online Help. The role is morphing into that of a content editor role: checking for consistency, spotting errors in marketing copy, rewriting copy, and so on.
So what is different? What has led to this wider scope? It may be due to us being recommended to them by word of mouth, and they had greater confidence in our abilities. It may be because they are a start up. It could be because many of the staff are not native English speakers.
We suspect it’s because the first project was the white paper. They had something that was very useful to them, for promoting the company. They also included us in their in-house chat system, which meant we could see other areas where they had issues with content. This led to us intervening more than usual, making suggestions in a proactive way. The growth of chat systems, such as Slack and Socialcast, within companies could open up other opportunities for other Technical Authors, as long as they take the initiative.
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.