Tyndale Technical Authoring

Developing products across continents

team-ii-1238320_resized

Image: B S K (FreeImages)

With the world growing ever smaller as communications advance, it is now increasingly common for even relatively small companies to operate across multiple sites in different countries. This not only allows them to gain access to different markets but also to avail themselves of a variety of available workforces for developing products. Thanks to the increasing use of video calls made over the Internet at very little cost, teams located in different countries can regularly ‘meet’ and share ideas, discuss progress and brainstorm solutions to problems. They can also develop working relationships in a way that voice-based calls do not allow to the same extent. Seeing someone’s face enables a much stronger relationship to be established and is particularly important when some of the participants are not speaking their native language. Add to this the rapid adoption of online project management tools for messaging and sharing documents, and many companies are successfully developing new products using multinational teams. This can be illustrated in two recent and very different projects undertaken by Tyndale.

Hard and soft options

The concept of ‘software as a service’ (SaaS), in which a software application hosted on a website can be accessed by subscribers, lends itself particularly well to development across multiple centres, as the results of changes can be viewed the instant that they are deployed by anyone with access rights and an Internet connection. We recently worked with a British-based company that has developed an online warehouse management tool specifically for e-commerce businesses. Although the product has existed for some time, the materials available to assist users were out-of-date, cumbersome to read and not readily searchable, which led to them being very underused. A new knowledge base was set up using Zendesk, and Tyndale was commissioned to review the existing documents, reorganise and reuse the information where possible, and create new content to bring the information in line with the current software functionality.

While the management team were based near Marylebone in London, the software was developed by a team in Lodz, Poland. Many of the employees in both countries worked from home on several days during the week and spoke to their colleagues as needed using Slack (for messages) or Zoom (for video calls). After an initial visit to the London office to be introduced to the key contacts, it was easy for us to slot into these working practices while working on the project. A demo user account for the warehouse management software was created so that we could ‘play with’ the product and learn about it. The existing user documents were made available via Google Drive, and the new content was created directly in Zendesk before being reviewed and published in the new knowledge base by the product manager. A Trello board was also used to manage the project so that everyone could see which articles were waiting to be written and which were being worked on or were ready for review and publishing. The project ran very smoothly and the first version of the knowledge base went live to customers in late 2019.

However, some projects do not lend themselves to this kind of remote working so easily, particularly those where a piece of hardware is being developed. Regardless of the sophistication of the available CAD models, there is simply no substitute for holding and operating the actual physical item when trying to describe a procedure to a user. An example of this was a new piece of explosion protection equipment that was being developed by one of Tyndale’s clients. While the technical director, who was our primary contact, was based in the UK, the company’s engineering team was headquartered in the eastern USA. Moreover, because the business was a subsidiary of an Austrian holding company, much of the development work on the product was carried out at their R&D site in Vienna.

Tyndale was commissioned to write not only the operating manual but also instructions for the assembly and refurbishment of the equipment, which would be used internally by the client’s manufacturing teams and service engineers. This entailed several visits to Vienna to witness the product being assembled and tested, with a chance to ask questions of the project team and take those all-important photographs. The writing work was then completed back in England, with questions and drafts exchanged via email with the teams in Austria and the US. The familiarity with the product that developed during these visits helped significantly when last minute changes were made following testing by the regulatory authorities.

Come the revolution…

It’s interesting to compare and contrast these two projects. The ability to work remotely on the explosion protection system was somewhat constrained by the physical nature of the product, of which there were very few examples available especially in the early days of the project. Whilst video conferencing could perhaps have been used more extensively than it was, merely seeing the product on a screen would not have been sufficient, especially when preparing the rather intricate assembly and servicing instructions. As anyone who has ever tried to work on a car will know, it’s often helpful if the manual tells you how to do something, not just what you have to do, and this can only be properly understood if the writer has tried it themselves. The visits to Vienna were, unsurprisingly, very pleasant, and there was a chance to socialise with the project team members after work which helped cement those working relationships that are so essential between humans.

What is perhaps more surprising is that the online warehouse software project worked so well even in the absence of such gatherings. Video calls made it possible for us to develop a good rapport with numerous people that we never met in person. At a time when the cost of travel, both financial and environmental, is at the forefront of business decisions, this is quite heartening. It seems that many companies, especially those with young workforces working in software development, have rapidly adjusted to a way of working that relies less on travelling and more on using an array of online tools to manage projects and resources. This has the additional advantage that people can work more flexibly as they don’t have to be in a particular location to do their job. Whether such flexibility can ever be accessible to more traditional engineering companies remains to be seen; the increase in rapid prototyping and further improvements in 3D modelling may help. However, even in these cases, the development of products across sites in multiple countries is still much easier now that it was even a few years ago due to the ease of communicating rapidly across the globe. There has truly been a quiet revolution in the way that the world works…

Firex 2019 – challenging the status quo

The annual Firex show at London’s ExCeL convention centre last week was an excellent chance to obtain an overview of the current state of the fire protection industry, one of the sectors in which Tyndale has been working for a number of years. The big players in the industry were well-represented but it was the smaller booths that most attracted the attention of Tyndale’s director, Robert Pallant.

One theme that quickly emerged from talking to exhibitors was that the shockwaves caused by the Grenfell disaster two years ago are still reverberating around the industry, and this is likely to continue for some time yet, especially as the government’s response to the tragedy is not yet fully formed. However, some changes have been implemented, such as much more stringent (and costly) testing of fire doors, which has caused many smaller manufacturers to struggle or even go out of business. It has also focussed attention on the intumescent layers in the doors – the strips of plastic that are fitted around the rim of the door and expand to seal the air gaps when the door is heated by a fire. There are firms available with technical expertise in these materials that can help door manufacturers design a material that conforms to their precise specifications and ensure that they can pass the more rigorous performance tests.

Another area that is seeing growth is the use of fire curtains. Long used in theatres to protect the auditorium from fires backstage, they are now increasingly being installed in open plan homes and offices, and even larger spaces such as warehouses. They introduce compartmentation in the event of a fire to prevent the rapid spread of smoke through the building and allow time for people to escape. They can be hidden discreetly when not in use but will deploy simply and quickly, even in the event of a power failure, and can withstand fire temperatures for 2-4 hours.

While progress has been made in the design of public buildings to allow access by those with restricted mobility, such as wheelchair users, some exhibitors felt that there isn’t enough attention being paid to getting these people out again quickly if a fire breaks out. This is also an issue for the increasing number of residents and patients in care homes and hospitals. There were a number of manufacturers of evacuation devices at the exhibition, including chairs fitted with skids that allow a single person to safely lower another down a flight of stairs.

Finally, even the venerable water sprinkler industry is arguing for a change in attitudes and culture in how we view their use. Life safety has rightly been the overriding priority for fire safety systems, but an industry association is suggesting that it is not sensible to design systems that allow occupants to escape from a block of flats, school, warehouse or factory, who can then only watch as it is destroyed by fire. Many fire services can evacuate and rescue people but do not have the capacity to rapidly control large fires and salvage property. Making the inclusion of water sprinklers mandatory in such buildings would, they argue, help prevent the total loss of facilities and infrastructure and greatly shorten the recovery time for organisations – surely a significant benefit to the nation which would justify any increased costs in the initial building construction?

With incidents such as Notre Dame in Paris and, very recently, the loss of a number of new flats in Barking, West London, reminding us that our centuries-long struggle to combat unwanted fires continues, it is encouraging to know that there are efforts in progress to challenge conventional thinking and change the culture of how we fight this battle. What seems to still be needed is clear leadership and coordination to drive these efforts forward.

Creating dyslexia-friendly documents

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.

Why product experts don’t write good manuals

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?

Too much or too little?

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.

Play to your strengths

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!

Manuals – why their day isn’t yet done

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.