What exactly is technical writing?

You might think that it is all about manuals, and instructions. Or perhaps architectural blueprints, or even the coding of the machines that produce things.

In an industrial setting that tends to split functions, we also tend to see a task as related to “our” function – where we are placed in the big picture, thereby leaving all the rest of the story to be told by others.

And maybe it has to be like that to be practical. After all, in a company with, say, 200,000 employees, producing thousands of different products across the world, to be sold on many markets, to many different people, you really can’t be in touch with everyone through all of this, can you?

I will claim that you can. And should!

Just like the product itself will be known by anyone from the initial inventors and designers over the production staff, the packagers, the distributors and resellers, and actually all the way through the recyclers – also the descriptions of the product can follow the product all the way.

Of course, different people need different information, but they all need some. By designing a totally covering package of information, you can control much of what is happening with and around your product, thereby avoiding unpleasant surprises such as a bad reputation for your product or your company, and shitstorms or other negatives in the public communication space.

Some of the places where technical writing is needed

1. The design process, for communicating the details between people involved in developing the product. This is both technical staff, including engineers, architects, designers, etc., depending on the product type, and people from the supply chain, sales, production, marketing, etc., who all need to be involved in decisions around a new product, to make sure that it can be produced and sold, and that materials can be sourced, and the product’s full lifecycle can be handled properly.

2. Production planning, where machines need to be purchased or made, space for the production itself arranged, as well as for all parts and their delivery paths, and needed ventilation and other safety equipment to be established. The product has properties and specifications that must be observed when planning all this.

3. Packaging design, where the product will need bags, boxes, pallets, etc., and both the visual appearance of the sales box or bulk packagings need to be considered, and also the practical aspects of how the product can be stacked (or not), and which conditions it requires when transported. Different versions of the products, or different sets (with different accessories) may then need careful considerations to ensure that there is an easy packaging process and also a clear way for resellers and customers to differ the products from each other.

4. Distribution and reseller nets, where many people need technical details of the product, including all procurement and sales people along the sales paths, but also those dealing with customs and other regulations. A carrier who transports the product, or many of them, will need to know about safety concerns, which chemicals are contained in the product package, etc., and every single person who ever needs to pick the right package should be able to do so based on product knowledge and the information on the box. Catalogues and part lists are needed, and so are specifications of related products, especially when a product is shipped in several boxes that need to go together.

5. Shops, be they internet or physical shops, need to show the product and describe it to potential buyers. They also need to know such as the size and weight of a box, to be able to both store it and ship it correctly. Most often, they will need a list of key information about the product, to be able to advise the customer and prepare various sales material. Everything to be sold through webshops should better be provided with a set of info, including headline, description, fact box info, pictures, etc., to reduce the risk that the shope does this wrongly (copy-paste errors are frequent in this space).

6. End users, who will need to know all about the product and its different features, how to use, maintain, clean, and dispose of it, and how to choose between different versions of the product.

7. Technical and other supporters, who need to assist anyone along the way, such as the end user or someone else who has anything to do with the product. There can be different levels of support, having different people involved with different needs for information, but they all need to know something about the product and how to use it.

8. Recyclers, who deliver an increasingly important part of the product lifecycle, will need to know which materials the product is made of, how it can be separated into its different materials, and how it all needs to be handled to provide a safe environment for the recycler and avoid pollution.

If you consider technical writing to be all about writing a manual, you’ll depend on various other people along the way to be able to extract from the manual what is needed for all of these, and more, situations of handling the product.

That requires a lot of trust in their skills! People who you don’t know, and who don’t know the product, should then be trusted to be able to understand all the details of the product and even be able to guide others.

Of course, this will lead to frustrating situations, unhappy customers, and probably both bad reviews and a shorter life for your product.

What to do

Whatever your product is and however you distribute it, it will make sense to consider the full path of the product from early idea to completely recycled, and find out what kind of information each of the people who will ever get involved will need.

This effort should lead to not just one manual, but a set of information, including such as:

1. Technical drawings, parts lists, etc. for production

2. Guidelines regarding manufacturing and the equipment needed

3. Guidelines regarding transportation and storage of the product

4. Guidelines regarding safety, including such as dealing with leaking chemicals, extinguishing fires, etc., plus safety when transporting and using the product

5. Guidelines regarding practical use of the product, not just the straight-forward cases, but also the special situation that some users will run into. Describe carefully both what the product can and cannot do.

6. Guidelines to supporting the product, especially regarding typical problem situations and typical errors and situations where the product may break.

7. Marketing input, to ensure that whoever design any kind of marketing material will have relevant information to put there.

8. Sales info, to ensure correct listings and descriptions in webshops and similar.

9. Box designs, meaning texts and images to be used on the product boxes and similar material. Some of this design will be up to marketing or product planning people (for instance, guidance on how to open the package or why the customer should buy this product) but various practical information about all the parts contained in the package, how to assemble these, what additional products (for instance consumables) are needed, etc. will need to be made available to the package designers.

10. Everything about the materials used and how they must be recycled or disposed of. This is relevant to many people along the way, including the ultimate recyclers, but also anyone who, along the way, experience a damaged product.

All of this information, most significantly, should be available in a form and a language that suits the people who’ll need it.

Current state

I have seen many product manuals for all kinds of products, from household machines over cars and trucks, to industrial equipment, and from food packaging over end-user medicine descriptions (inlay notes) to medical study reports. My impression is that most of the needs for documentation have been recognized by the manufacturers, but very often it has been provided in a generic way that often doesn’t fit the situation where it is needed, or the people who need it.

A hospital bed may be equipped with some information directly on the bed (through printed or stamped text, or stickers) for the personnel at the hospital to use. In this special field, the information is often very well-designed for specific use cases. Nevertheless, a manual will often be needed, and perhaps also a course, to get started, as the messages on the product itself tend to be rather diminutive.

In such a professional environment like a hospital, the needs for information will be covered, simply because they have to be, and the hospital itself, or some consultants hired for the purpose, might create and share any missing information themselves.

In less professional environments, however, it often goes wrong. It is typical for a shop to not be able to help a customer with information about a product, for instance, because all the knowledge they have access to is the sparse, advertising-like, text snippets on the product carton.

Support telephones (or increasingly FAQs, etc.) often just ignore any request for practical, technical information, because they don’t have it, or they cannot spend the needed time to provide it.

A manufacturer can do a lot here, by providing useful information in a format suited for the different people who need it – for a customer support, for instance, an easy-to-overview list of need-to-know, typical problems, and practical guidelines, would be very helpful.

Of course, it is not all on the manufacturer’s shoulders, as a shop might be run in a diminutive way that deliberately exclude the technical support and simply either ignore their customers’ needs or by standard just pay back the money.

Your choice

Which kind of manufacturer would you prefer to be:

1. The supportive, informative manufacturer with happy, returning customers

2. The distant (maybe even unknown) manufacturer who sells one item to each customer, after which these decide to never buy any of your products again

That’s actually the kind of choice you’re making when deciding on your strategy for how you provide technical documentation.

Back in the 1980s and 1990s where personal computers entered the office space large-scale, one of the most used terms was office automation.

Before the personal computer (PC), some large companies had mainframes with terminals, and some smaller companies had mini-computers, as they were called — also with terminals, just in a smaller scale than the mainframes.

A PC was not very capable at first. It allowed for certain tasks to be performed, but we still had to do many things on paper and by hand. So, the automation of typical office tasks seemed like a futuristic dream more than a short-term goal.

Enter Wordstar and WordPerfect

Even though the PC-world saw many programs already in the early days, only a limited amount of them managed to gain a serious momentum. This included word processors of which Wordstar and WordPerfect were early out and became the most popular in the 1980s — and the latter continued its success until the beginning of the 1990s, then losing its dominance because all the users had moved from DOS to Windows, and WordPerfect didn’t work well on that platform. Microsoft Word did, and, hence, conquered the world.

But during the WordPerfect years, the many secretaries who had been working on typewriters until then, needed to learn word processing, and, in particular, learn how to use WordPerfect, in order to be employable.

Typewriters died out rather quickly when first some nicely printing printers (laser printers) appeared on the market around 1985 and going forward, and the only need for typewriters was then to help filling out forms with the hard-to-kill carbon paper for creating multiple copies (carbon copies).

Secretaries were still needed, because their work and the use of WordPerfect was considered a specialist role that most other people in the company couldn’t handle.

The secretary’s role

I am sure that there has been many different activities carried out by secretaries during times, but when I entered the professional life in 1994 after finishing my first education, there were still secretaries in each department and in each larger project.

A secretary would often write letters and other communication pieces, but they would also write technical documentation. Often, at that point in time, getting files with some input from the software developers or other technical staff, and use this input to generate better and more coherently written descriptions — following a standard and fitting it into a binder that each of us, taking part in the project, would have on our bookshelf. That binder was the manual, the development reference.

Also, the secretary would print and photocopy, stamp some holes so that the copies could be put in the binders, and walk around the office to hand out to all of us all the nice new additions and corrections to the manual.

And this was needed, because printers were rare in the office space — only a few of them existed, and since the network wasn’t well established at the time, and the printers in particular were not connected to it, it wasn’t possible to just email us the corrections, for us to print them ourselves — which by itself would be difficult, as email was something new that most of my colleagues (in a leading software development company) didn’t use.

So, we were highly dependent on the project secretary, who also did many other practical things, such as taking notes at meetings, writing memos and distributing these (good to have as a proof if later a disagreement with a customer would materialize) and coordinating quality system efforts, collecting time sheets, writing reports, etc.

But then the lightning struck

It happened during a short time, in many companies. It was decided by the upper management that since everybody now had a computer, they could write things themselves — so, the secretaries were not needed anymore. And they got fired. Apart from the CEO’s secretary, of course, since the CEO had better things to do than writing letters.

All the rest of us apparently didn’t have better things to do. Software development had until then been our 100% occupation, but now it would be 80% or less, because we needed to spend time on writing documentation, photocopying, and millions of other things that hitherto had been done by the secretaries.

This led to less efficiency and also to lower quality in all these new tasks that many of us weren’t qualified for. A lot of the tasks were simply not performed anymore, and such as memos from meetings started dying out as a discipline, because none of the meeting participants wanted to make them — or made such poor memos that they were considered useless.

The lack of documentation

What the top management had not realized when firing the secretaries was that writing takes time. It is not something that you just do during the last 10 minutes before leaving the office. You need to set aside a significant part of the project time for this, if it should end up being done to a good level.

Also, most technical employees cannot write. They know the alphabet and how to spell words, mostly, but putting together larger amounts of text is not their thing — so they are not doing it.

Because of this, we went from prioritizing documentation, both internal and customer facing, to dismissing it altogether.

I remember how, after a few years with this situation, contracts began stating a simple “there should be user documentation” instead of the previously more rigid descriptions of all that the documentation should contain.

With the hastily progressing Internet, information became easy to find, so people began in many cases to search externally for every bit of information they needed in their work, rather than trying to get details out of their colleagues.

We had, effectively, lost the skill and discipline of documenting our work and products.

The situation today

Intranets appeared, and they were meant to facilitate “the learning organization.” It was, however, difficult to make all the employees write on it, or even using at all. The dream of an organization where everybody shared their knowledge was exactly just a dream - it never happened. People were supposed to share knowledge - another term for write documentation - but as they couldn’t do that previously, they still couldn’t do it. Intranets became, by large, a complete failure.

But along the way a variety of the intranet did manage to gain some momentum: Atlassian Confluence. It was not the only attempt to make a simple platform for keying in almost whatever you want in almost whatever form you want to give it, but the fact that it was the sibling of Jira, a project management tool for the modern age, made many companies buy Confluence and start using it.

Still not a huge success in all companies, but many developers do like to write a little bit now and then, if it is not too formalistic, and so it is being used in some companies by some teams.

In contrast, the customer facing documentation need has not only escalated in amount — a result of the higher productivity today in software development, which makes it difficult to set enough time aside for documentation when also programming — it has also escalated in variety and quality:

Variety means in this case that there are many different things to document, and they often need to follow certain common standards.

Quality considerations are the direct result of all the competitors’ documentation being available on the Internet, just a few clicks away — so it has become a competition parameter to have good documentation for a software product or service.

The paradox: more is needed in a higher quality, but technical people are hooked up on their main tasks more than ever, and they still cannot write and still cannot find the time for neither learning it nor doing it.

The solution

It is already going on, but more is probably needed. In a world that produces millions of texts each day, and where millions of products can be bought from anywhere, it is surprising to see how few guidances to using the products are among those texts.

Next to the limited availability of technical manuals, the quality is also missing out completely in many cases, for instance when poor translations of an already poorly written manual are put in the product package.

For software, you will often look in vain for the documentation — it may not be there at all. Or it is hidden in helpdesk forum discussions or similar and very hard to find.

If you have bought or updated your Windows or macOS recently and wanted to get help for a function or just more information about it, you most often cannot find this, because it was never written.

Software with billions of users — billions! — doesn’t have any manual.

If just a tiny little fraction of the money this software brings in would be spent on writing documentation for it, we could have full sets of excellent descriptions of everything in the software.

Smaller software products, with fewer users, bringing in less money, would perhaps have to be documented less, but it would still be possible to get a long way with spending just a tiny fraction of the development and marketing costs on documentation.

Of course, there are people who will not read it, others who do not understand it, and yet others who will be unhappy with whatever will be made. But there will be millions — or billions — of people in this world who, each and every day, would be grateful for the effort.

I think that this is a good case for increasing the activity of technical writing - for companies producing anthing technical to also start producing the needed technical documentation, and for writers with technical knowledge to consider if this could be one of their ways forward.