In an article first published in ISTC Communicator in Spring 2019, Robert Pallant suggests ways to make content more accessible for those with reading difficulties.
In an article first published in ISTC Communicator in Spring 2019, Robert Pallant suggests ways to make content more accessible for those with reading difficulties.
When considering the writing of product manuals, one question that often comes up is, why don’t the people who designed and built the equipment write the manuals themselves? At first glance, it seems like a sensible suggestion – they will know the product and its many features inside and out, and may also understand how they can be used to meet a specific need or serve a particular application. Surely there’s no-one better to write the user’s guide?
In fact, there are a number of potential issues with this solution. In most cases, the product specialist is a fundamentally different person from the end user of the equipment. They (the specialist) understand every nuance of the product and have lived with it on a daily basis for many months or even years. They are likely to have forgotten a time when they didn’t have a deep understanding of the underlying technology, and so the tendency will be for them to assume too much knowledge on the part of the user. They will also lapse naturally into the jargon of the subject, as this is part of their everyday language.
Users, on the other hand, are often not specialists in the field at all, and frequently don’t need to be; they use the equipment as a tool to help them perform one part of their job function. They will thoroughly understand the application of the product, but won’t necessarily need to know every aspect of how it meets their requirements.
Whilst one instinct of the experts is to assume too much knowledge, another is (paradoxically) to impart too much information about the product. Those who are responsible for creating a new product will be understandably proud of it, and are quite likely to describe every nuance of every feature, mode and option, rather than focussing on those that the user will find the most valuable. The expert’s familiarity with the product makes it hard for them to imagine how a new user would approach performing tasks, and so while the expert might routinely use a shortcut, a new user might find this counter-intuitive and would be better advised to follow a more methodical approach until they are familiar with the product.
Finally, there is perhaps the most fundamental problem: most developers work in their discipline precisely because they enjoy developing new products. Writing about a product they have spent ages developing isn’t necessarily their favourite task! It can take longer than expected to complete a manual, mainly because the product also needs to be fully completed, which often doesn’t actually happen until it enters production (if then!). By this time, the specialist will be deep into the next development cycle, or working on a completely new product, and won’t welcome the distraction of trying to complete the writing of the guide for a product they regard as finished.
Engineers are adept in grasping technical concepts and are strong in science, mathematics and logic. They can prepare highly technical specifications that describe the product in detail to other specialists. However, these skills do not necessarily prepare them for the task of writing for non-specialists. This is where a technical author can offer real value to a business.
Technical authors bring the approach of engineering to the task of writing, by building up documents in stages to create a finished product that is fit for purpose and specifically designed for its readership. They learn about the product; they ask questions of the experts (an essential source of information); they break the information down into logical steps (for procedures) or succinct chunks (for general descriptions). And they do this with the big advantage that they are not experts in the product, which allows them to place themselves in the shoes of the user much more easily and tailor the content and presentation to suit them.
So while it might seem that a product specialist would be best placed to write a manual, in practice this is often not likely to produce the best manual for the user. Better to ask a writing specialist – a technical author!
© 2019 Tyndale Technical Authoring Ltd
Most technical authors cut their teeth by writing or at least maintaining either a user’s guide or some other form of manual. Even software-based technical authors who write Help content are essentially writing a manual for using the software application. For decades they were the preferred, perhaps even the only, form of technical communication that was available to explain a product to a new user. However, we in the technical communications industry are constantly hearing about the need to move beyond manuals and embrace new ways of communicating content. Many consumer products no longer come with a comprehensive manual; a basic start-up guide then allows users to access online content to help them answer questions. Although this trend is significant and important, it’s been our experience that the traditional manual still has a lot of things going for it.
Firstly, as we’ve discussed in a separate article, manuals are usually a regulatory requirement. However, it would be doing a disservice to manuals to use this alone as justification for their continued existence. Manuals are a very useful source of reference material for a product. Settings and their meanings are often most easily understood by consulting a list in a manual. Terminology is easily explained in a glossary; symbols and their meanings can be quickly found in a table; connections between components are simple to follow in a clear, well-designed diagram.
In technical communication, one size doesn’t fit all; each method of conveying content has its pros and cons. Innovations like online video and augmented reality are complemented by a manual when it comes to complex products with multiple operating modes. It’s often true that a well-made online video is a more effective learning tool for a complicated physical operation than a series of pictures and words in a step-by-step procedure. However, it rapidly becomes somewhat tedious to sit through it again and again to find that one step you can’t remember; easier to flip to the page in the manual showing the appropriate step and have it next to you while you work through the operation. While the video in this case is the initial teaching aid, the manual reminds the user of what they have already learnt the next time they need to perform the same procedure.
This highlights another point that may cause innovators to hold their heads in despair. Many companies save money these days by only producing soft copies of their manuals, usually as PDFs. This is not really the best format to view and navigate easily on a screen, and the tech comms industry has woken up to this by creating HTML-based formats that are much more suitable for tablets and smartphones. Of course, electronic manuals can be downloaded to your mobile device in advance of a service visit, as many plant rooms still seem to be in black spots for going online, and the documents are certainly easier to carry around this way. However, you still need battery power to read them, and somewhere to balance your expensive piece of electronics while you use both hands to work on the product. A printed manual doesn’t need wi-fi, mobile phone signal, or even electricity to read (beyond a light source). It’s simple to add your own notes or comments, making the manual a living document that is customisable to suit its owner, as well as assisting with providing feedback to improve future revisions. And it seems that we humans still have an affinity for paper when it comes to long-ish documents; after all, the demise of the printed book was predicted in the face of tablets and e-readers, and yet their sales remain strong.
So don’t be too quick to dismiss the manual as yesterday’s solution to communicating technical content. It’s easy to be distracted and diverted by the innovations that the burgeoning world of digital technology can offer; many of these certainly offer some intriguing possibilities to help enrich a user’s experience of a product, but neither are they the answers to all our needs. Manuals still provide a strong and stable foundation upon which all other user assistance can be built.
© 2018 Tyndale Technical Authoring Ltd
Technical authors are often confronted with the spectre of the user’s manual when we mention what we do for a living. It is invariably the most universal example that we can give to shine a light on the largely hidden world of technical authoring, although it usually leads to someone recounting a story about instructions that completely failed to convey how to build or operate something, to which we can only shrug and mumble something about how companies should use professional technical authors to create such documents…
The fact is that it isn’t easy to write a good manual. One reason for this is that they are a regulatory requirement. The submission of a manual is a mandatory part of all the product compliance submissions with which we’ve ever been involved, and so it isn’t surprising that many clients request a manual as one of the first things that they need from a technical author. Products must be accompanied by some information which purports to help the end user to safely handle and operate the item. It must describe who produced it and what the potential hazards and risks are in using it. It must also attempt to anticipate the consequences of any misuse of the product and provide warnings and advice on how to avoid them. And therein lies part of the problem.
Manuals have often become repositories for every fragment of information needed to ensure compliance and limit a company’s liability, causing them to become bloated and difficult to navigate. If a company can say “it’s in the manual” then they at least feel that they are legally in the clear, even if this makes the manual so unwieldy and tedious to read that no-one bothers, thereby negating the benefits of all this valuable corporate wisdom. However, with the current popularity of seeking compensation, it seems unlikely that companies will strip out all this legalese from their manuals any time soon.
This trend certainly increases the need for manuals to be well-planned, carefully structured and clearly written to maximise their usefulness. Words should be used as economically as possible to convey the message clearly. Terminology must be unambiguous and consistent. Clear diagrams and photographs can be of great help although, flat-pack furniture assembly instructions notwithstanding, they are rarely sufficient on their own.
Careful consideration must be given as to what to include and, equally importantly, what to leave out. Where there are multiple ways of performing the same operation, something for which software is particularly notorious, there are often strong arguments against describing them all as it becomes too confusing, especially for a basic level new user. It can also be argued that most users do not need to understand exactly how a product works. While a superficial appreciation of what is happening can be helpful in using the product sensibly and diagnosing simple faults, an in-depth description, if needed at all, should be included as an appendix and not allowed to complicate or obscure the essential information.
Targeted manuals can offer a good solution against the tendency to include too much information. A quick start-up guide that covers the basics can be invaluable to getting a product up and running quickly. More advanced manuals for more adept users can follow later. Alternatively, looking from the manufacturer’s viewpoint, comprehensive service manuals can act as useful stores of product knowledge, containing valuable hints and tips gleaned as the product matures. These too need careful structuring and indexing if information is to be easily found, although the advent of electronic manuals now helps with this by providing a search facility. These documents can also act as valuable fault-finding guides for both users and technical support staff, and with email and the cloud allowing manuals to be rapidly sent around the world, the onus on the user not losing their one copy of the manual has reduced considerably.
Another important aspect of manuals which is easy to overlook is their role in supporting the company’s brand. The documentation that a user receives to help them understand and use a product says a lot about the company that supplied it. Not only should the manual adopt the same visual appearance as other marketing material, it should also feature the same style and ‘tone of voice’, so that it acts to support the rest of the company literature and reinforces the brand’s values.
The mandatory requirement for manuals, which can make them seem like a burden for companies to produce, can hide the great potential benefits that they can bring for both the manufacturer and the user – when they are well-written, of course!
© 2018 Tyndale Technical Authoring Ltd
Tyndale has several clients who specialise in various aspects of fire protection, and so its director, Robert Pallant, took the opportunity to visit this year’s Firex show in London’s Docklands to catch up with the latest developments in the industry.
It’s been a tumultuous year following the horrific Grenfell Tower fire almost exactly 12 months ago, and the exhibition reflected that with a separate event focussing exclusively on protection of high-rise buildings. Several delegates and exhibitors stated that they had seen increased interest in issues such as intelligent PA systems that allow a phased evacuation depending on the location of a fire, and protection of escape routes with either passive or forced ventilation (which also supports the sustainable heating of buildings, an increasingly important topic for environmental reasons). However, while these measures are being introduced in workplaces and, increasingly, student halls of residence, the uptake in other residential buildings is still low. Whether the Hackitt report into the current fire regulations, published only a month ago, will cause this to change is as yet unknown, but ongoing demand for the industry’s products seems assured.
Among the other factors driving growth is the massive infrastructure investment going on in Qatar in preparation for the 2022 World Cup – appropriate as this year’s event in Russia was in progress while Firex was on. One exhibitor, from a company in Cornwall that provides seals to prevent flames passing along cable ducts, reported a growth of 70% last year, largely driven by exports to the Middle East.
There were some terrific examples of innovations on display too, including: a fire door retainer that can be “trained” to only close the door in response to the sound of your fire alarm; a low-cost network of smoke and carbon monoxide detectors that sends status updates to an online application using a single mobile phone SIM card; and sheets of glass containing a liquid layer which swells and expands on the action of heat, reducing the temperature on the other side of the glass to allow time for escape. Perhaps most unusual was a backpack containing a winch that can lower the wearer 15 storeys to the ground on a thin steel cable, before winching itself back up for the next person! The trials for that product must have been nerve-wracking…
Fire safety glass containing liquid intumescent layers that react when heated to insulate the far side of the window
Tyndale has recently started working with a company in the Netherlands to document business-critical test procedures which currently reside in the mind of a single test engineer.
Berson Milieutechniek BV designs and manufactures ultraviolet water treatment systems to the industrial and municipal water supply markets of countries around the world. Owned by Halma plc, it has for many years operated in partnership with Hanovia, a UK-based UV water treatment business with whom Tyndale has worked for the past three years. This partnership has now become even closer with the merger of Hanovia and Berson in October 2017.
Established in 1972, Berson is located on the edge of the charming Dutch town of Nuenen, a former home for Vincent Van Gogh and where he created one of his most celebrated works, The Potato Eaters. A sculpture depicting the scene in the painting sits in the centre of the town, as well as a statue of the man himself and a museum devoted to his time in Nuenen.
Just as artists like Van Gogh captured scenes from everyday life in past eras, so technical authors work to capture essential knowledge and expertise which could otherwise be lost if it exists only in someone’s memory. Tyndale has been helping Berson in this regard by documenting how their test engineer checks the functionality of their UV treatment systems before they leave the factory for the customer’s site. This testing is a critical step in ensuring the quality of the product, and it has been greatly enhanced by the construction of several bespoke test boxes; however no-one else on the site is familiar with them. It was realised that this lack of documented knowledge posed a risk to the business, and so, with the engineer’s full cooperation, Tyndale has worked to capture the essential steps and provide a clear, logical method for completing the tests.
This work will enable another competent engineer to perform the testing in an emergency or to help meet production schedules during periods of peak demand. It also gives everyone concerned the chance to review the process and check that nothing is missed or could be done better – an important aspect of any strategy for continuous improvement. Once completed, the procedures will cover the majority of the standard products offered by Berson, but they also provide a template on which future procedures for more specialised products could easily be based.
An online user’s manual created by Tyndale is now available for pilots and aircraft operators using FlightPlan, a web-based software application from Hampshire company RocketRoute.
FlightPlan helps users plan a route for their flight, calculate fuel requirements and file the flight plan with the relevant authorities. It also gives users access to valuable information about the location and facilities of airports and aerodromes, as well as comprehensive weather forecasts for Europe, USA and South America. It is designed for anyone with a need to file a flight plan, from individual private pilots to operators of small and medium-sized aviation enterprises.
Until recently, the manual was a PDF-based document that was distributed separately to customers but which was awkward to keep available and up-to-date with the latest features in the software. Tyndale recommended moving to an online manual that could be quickly revised as needed and which would be accessible by all users at any time.
The manual was created using Adobe RoboHelp authoring software, and first went online over the summer. Such is the dynamic nature of this software, it has already been updated to version 1.1 to reflect improvements in the available tools for managing crew and passenger details. This version, which was posted on the RocketRoute website in October 2017, can be viewed in an Internet browser by navigating to www.rocketroute.com/help and clicking Read the Manual.
Robert Pallant, Director of Tyndale, commented: “We are delighted to have worked with RocketRoute on modernising and improving the support to their customers. It’s also been fascinating to learn more about the aviation industry and the varied needs of the FlightPlan users. While PDF-based manuals still have a place in many industries, a web-based guide that can be readily maintained and updated is more appropriate for an online software application. We look forward to continue working with RocketRoute to keep the manual updated and useful for customers in the future.”