Adobe released the latest version of RoboHelp last week, and we’ve taken it for a quick spin around the block. It’s called RoboHelp (2015 Release), but we’ll call simply call it RoboHelp 2015.
Writing in the business world can be difficult. We have to write Web pages, proposals, emails, policies and procedures and, perhaps, adverts. It can be hard to get going, and create something that’s clear and to the point. Here are some tips to help you get over these difficulties.
It’s not your fault
Let’s start by saying it’s not your fault if you find business writing difficult, because most of us are not taught how to do it at school. At school, we learn how to write stories and how to argue a case. That usually involves building to a big conclusion at the end.
In business, mostly we have to write to:
- instruct, or
Those are different forms of writing.
“Everyone is taught to write at school, so surely everyone can write in business?”
Although the quotation above would seem to make sense, the reality is that many people find it hard to write in a business context. They struggle to write clearly, and it can take them ages to produce a piece of content.
It’s not their fault. What we’re taught at school is how to write narratives, that is stories or articles. We’re also taught to argue a case – to use rhetoric to build to a conclusion. We’re taught writing to persuade and writing to entertain.
In the world of business, we often need different forms of writing. We’re often writing to inform or writing to instruct.
In these situations, people want to know what they should and shouldn’t be doing, and get on with their jobs. They want the important information at the beginning, rather than the end. They want to scan and hunt for the information relevant to them, rather than always having to read everything from beginning to end.
Many people haven’t been taught how to write to inform or to instruct, and that’s why many people find business writing so difficult.
The airline safety video is about actions that could save your life, but it can be very dull and mundane if you’ve flown more than once. So airlines are using the third aspect in good design – emotion – to engage with their audience.
The latest video to follow this trend is from Delta Airlines:
Other examples are:
Google’s Riona MacNamara presented at the Write The Docs North America conference on “Documentation, Disrupted: How Two Technical Writers Changed Google Engineering Culture“. In the video of the presentation below, Riona explains how she worked with a small team of writers and engineers to build a documentation platform in six months that is becoming a part of the standard Google engineering workflow.
Mozilla is an organisation that always seems to be doing innovative things with their documentation. One of the experimental functions it has introduced to its Kuma wiki platform for the Mozilla Developer Network (MDN) documentation is an experimental PUT API that makes it possible to create and update articles remotely.
Mozilla suggests a number of ways it can be used:
You can create a page for your project and update content in certain sections from automated build, testing, and deployment scripts. This can help you keep your community up to date with your project’s progress.
If your project offers documentation alongside source code, you can push HTML renderings into a subsection of MDN. This lets you maintain docs in a way that’s appropriate for your team’s workflow, while still contributing to MDN and allowing localizers to translate the content.
Fro example, Mozilla’s programmers are able to write scripts that automatically generate articles based on contents of header files they’re creating. The API uses HTTP, which means software engineers (and other writers) effectively have the freedom to use the application environment and libraries of their own choice.
Kuma itself is an open source platform written by Mozilla in Python, using the Django framework. Contributors can fork the Kuma repository on Github, make changes to the content, and push the revised content back to the wiki.
It will be interesting to see if this succeeds, and if this type of platform extends further out than its use for developer documentation.
It might seem like we’ve been quiet recently, but that’s partly because we’ve been working on an academic project that we hope to be announcing towards the end of the year.
As a spin-off from this project, we’re developing new training courses in technical communication. These courses are at a more advanced level than our basic/intermediate courses, and they include more references to academic research.
If you are considering any on-site training for your technical communications team, we can now offer these topics:
- What is technical communication?
- The business case for technical communication
- History of technical writing standards
- Usability and user centred design
- Project planning and its effect on writing documentation
- Researching and scoping documentation
- Information design and content organisation
- Writing the topics – overview
- Presenting different types of information
- Index, search and metadata
- Single sourcing and reusing content
- Post writing
- Researching technical communication – where to go
- Establishing standards
- Governance and maintenance
- What skills does a technical communicator need?
- Content strategy and technical communication
- Trends in technical communication
- Visual design
- Publishing and delivering information
- Managing the documentation project
- Metrics/Evaluating documents
We may develop online courses for some of these topics in the future as well.
Here’s a summary of recent activities:
- We have a client looking to engage a technical editor for a three month contract.
- We have a client looking for an undergraduate (or recent graduate) to spend 6 to 8 weeks as a paid technical writer intern this summer.
- We’ve a client looking for information on applying Net Promoter Score to user assistance documentation. If you’ve seen anything, please let us know.
- Cherryleaf’s Ellis Pratt will be the guest speaker at June’s “Member Masterclass @ The IoD”. The topic is clever content creation in business. We’ll look at some of the most effective techniques for creating the types of content created in today’s business world. The event will be held at 6pm on 2nd of June 2015, at the Institute of Directors, 116 Pall Mall, London.