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.

I know, it isn’t anything new, really: times are changing. They always do, have always done.

Translators who were in the business 20 years ago or more, remember how the work was completely different then, with better payment and longer deadlines, more time to spend with dictionaries and other reference material, most often with a focus on making the best possible translation. Now, on the contrary, payments are low, deadlines are short, and there’s no time to fiddle with books and other slow media, at most a few searches on the Internet throughout the whole task, or otherwise it will be impossible to deliver within the time and price constraints.

But some more disruptive elements have appeared: First, the translation software that evolved into online services, and then the machine translation, now integrated everywhere, in almost every translation process out there. But lately, even machine translation has been pushed aside by AI, which is providing more fluent and seemingly creative target texts, and often without any linguistically inclined people taking part in the process.

Things are moving fast. Very fast! Just within the last two years, I have personally seen a situation in the market going from having enough of work to fill out my time, even if some of it was paid below a reasonable minimum, to now seeing several weeks pass without any tasks at all. This means, realistically, that I am no longer living from translating, and soon I will have to give it up completely, taking on some other work instead of reserving time for the translation tasks.

During those last two years, prices have been at a standstill, at best, or been reduced. Most often, they are simply frozen at the levels I agreed on with the clients (mostly translation agencies) about eight years ago, when I started doing this for a living. Attempts to increase the prices along the way have mostly failed, as any request for a change is met with silence, followed by fewer tasks than before.

There was an agency recently, who agreed to increase the rates. They even had some new kinds of tasks, a new language pair for me to work with, and it sounded good and prosperous, since they had a new client with this need, and I was so far the only translator who could do it.

But since we agreed on the new rate and the extra language pair, I have seen close to no tasks from them.

Another agency went too far, in my opinion, with their demand for free afterwork, when I had delivered the fifth round of additional “corrections”, including the implementation of some new preferred translations for common phrases, they had found and decided upon after I had initially done the work – plus several other new elements of work that were not in the original contract. As they came back with the sixth round of “QA”, as they called it, even though it had nothing to do with fixing errors, and as I had already spent at least three times as many hours as I had been paid for, I said stop. My claim was that they had already got much more than they had paid for, and if they wanted anything further, it would cost extra.

I haven’t heard from them since. It was several months ago. That is, a task was offered, I said yes, and then I heard nothing more. And later, again the same. A couple of weeks ago, they offered me a larger task, with work every day during a period, to start “in two days” – but no purchase order appeared, and when I asked them after the two days, by email, what happened to the task – I got no response.

And this is a pattern I see more often now, also from other agencies. More demands for less money, and fewer tasks altogether.

I do get emails with requests, and I do send estimates, prices, CVs, etc., as they ask for, but then I hear nothing more. One agency sent me a general collaboration contract, not long ago, after we had talked about a specific task, and I signed it and sent it back. I still haven’t heard from them, never got a copy with their signature.

One more significant change is, as mentioned, that AI has entered. Two years ago, I don’t think it was mentioned by the translation agencies at all. Now, at least half of them have announced some kind of activity in the area, and several tasks for correcting AI output have been offered (but without follow-up when I say yes).

It has long been a common topic on social media, amongst translators, that the business is in a decline. Some have blamed the cheap workforce of the East, now available through the online translation tools, and others have blamed the loss of quality sense, or the focus on price rather than quality, or something else. Many have declared the translation business, as we have known it so far, for dead. But now, honestly, it really does look like it is close to being dead.

Most translators I know see similar problems as those I have described, plus, a more and more common phenomenon: the request for work to be done for free. Not many translators ever experience any appreciation of their skills and enthusiasm, their wish and will to make every translation perfect and work with it until it is.

In fact, most translators seem to see the same as I do: that it is impossible to live from it anymore. It can, at best, be a hobby that is being exercised a couple of times per month, perhaps for a symbolic payment.

So, while the society is moving towards letting AI do everything that has to do with words, skipping all human activities, the humans – the translators – will just have to move somewhere else.

We no longer fit into the society. We have reached the end of our journey.

Similar to what happened to another of Inidox’s substacks just a day ago, A Rich Life, Technical Writing has been moved to its own domain under the general Inidox domain.

From the first try, I have learned that everything goes 100% smoothly and all links from before will continue to work, hence, you should not run into any problems whatsoever because of this transition.

As a custom domain is often recommended, mostly because it in some undefined way seems to help with the branding of a site, I have high expectations. Many new subscribers, top position on Google searches, and a large inflow of requests from new customers :)

Well, I am realistic, so a slight improvement in my own and perhaps other’s ability to remember the domain name would be expectable, and everything else will just be a bonus.

Also, the sites Technical Writing DK and Data Analytics are in the process of getting a custom domain, and that will complete the circle. Everything should be up and running within hours from now.

Please let me hear if you experience any trouble due to this change.

Welcome to Inidox’s page on Substack, Technical Writing!

I hope that you’ll enjoy what you find here – now and in the future. We will now and then add more articles of different kinds and styles to cover the big and diverse world of technical writing and translation – and whatever we can think of that could be interesting in this context.

If you look at the Home tab, you’ll find several sections after each other. The named sections are, at the same time, also the names of newsletters that you can subscribe to with your page subscription.

The newsletters will be sent by email each time a new article is posted in the section, typically containing just that one article.

You can adjust your selection of newsletters by hitting the menu item called Newsletters and then the link account settings on the page that opens. This will bring you to a page where to can toggle the newsletters you want or don’t want. This, of course, can be redone in the same way as often you wish.

Next to this page, Inidox has a few additional pages.

One is with similar contents as this one, but in Danish language. So if you understand that language, you may wish to subscribe to that one too, to get more information about Inidox and our favourite topics – technical writing and translation.

Another is about data analytics, which is also a big thing for Inidox.

And, finally, the creative writing also has its place on its own page.

Please feel free to subscribe to the pages you want, and then, like for this page, you can adjust your subscription for each of them to suit your need. The default is always for our pages that when subscribing to a page, you’ll get all the newsletters.

I hope they are interesting for you and I will see you there too!

Technical Writing by Inidox - DK

Inidox leverer technical writing, oversættelser og dataanalyse - denne Substack er stedet, hvor vi taler om at skrive teknisk - på dansk.

By Jorgen Winther

Data Analytics by Inidox

Inidox provides technical writing, translation, and data analytics - this Substack is where we talk about everything related to data and how to work with them.

By Jorgen Winther

A Rich Life by Inidox

There are so many things to enjoy in life! So many thoughts about it. Explored through short stories, poetry, photos, drawings, observations, and everyday philosophy.

By Jorgen Winther

This is a conversation space exclusively for subscribers—kind of like a group chat or live hangout. I’ll post questions and updates that come my way, and you can jump into the discussion.

Join chat

How to get started

1. Get the Substack app by clicking this link or the button below. New chat threads won’t be sent sent via email, so turn on push notifications so you don’t miss conversation as it happens. You can also access chat on the web.

Get app

2. Open the app and tap the Chat icon. It looks like two bubbles in the bottom bar, and you’ll see a row for my chat inside.

3. That’s it! Jump into my thread to say hi, and if you have any issues, check out Substack’s FAQ.

Translation happens all the time, all over the world. We have so many different languages that the need occurs for a large part of everything written — and that’s a lot.

But how does it happen? Or more precise, what steps do you go through when managing a translation project?

People who work in the industry knows this, of course, and yet they sometimes behave as if they don’t. For instance, when hiring a freelance translator for doing the translation, and then expecting that all kinds of additional tasks will be done on top, most often for free.

End-clients who hire a translation agency for the translation will often be met by some questions about what exactly is needed. A corresponding price list may then help understand how the project actually consists of many different tasks. Each of these will take some time, therefore cost some money.

The possible steps

Projects are different — that’s why they are projects and not just “operation”. But a translation could involve several or all of the following, and in some cases even more different tasks:

1. Project management

2. Translation

3. Proofreading

4. Second proofreading

5. Linguistic Quality Assurance (LQA/QA)

6. Desktop Publishing (DtP)

7. Post Layout Review (PLR) / Linguistic Sign-Off (LSO)

Additionally, to make these activities work, there will be parallel tasks such as:

8. Sourcing or creation of termbases / glossaries

9. Creation and administration of translation memories

10. Questionnaires and processes for translators etc. to evaluate each other

11. Administration

Obviously, when hiring a freelance translator or a translation agency to “simply do a translation”, it will mean much more than just that.

Let’s look at the individual tasks.

Project management

For an agency translation project manager, there is typically an initial step of qualifying an incoming request from a client, and to see if there are any translators and other relevant parties available — then determine a possible deadline for delivering the translated text, and making an agreement with the client. Along this process, agreements with translators, reviewers, and others will need to be made as well, so there is a lot of purchase order writing and price calculations involved.

It varies between agencies if they have their own staff or depend fully on freelancers for translation, proofreading, and some other tasks, but mostly they have in-house people for project management, QA, DTP and administration. Still, with in-house resources, it is needed to assure the availability of these when they are needed. So dates and times of day must be planned and coordinated with quite many parties — often within a very short timespan, as the client will expect a reply to their request within a few hours.

During the project, all the normal project management activities, like for projects in other businesses, will be done, but with the typical addition of also working with the translation tools to some extent, for creating projects and files to be sent, importing and exporting files, etc., for all the relevant parties to get what they each need.

Most translation projects will make use of a Computer Assisted Translation (CAT) tool, which is a clever construction that can split the text into segments (basically everything between two end points), present these segments in a list for the translator with space next to it for writing the translation. The tool will keep track of all formatting and can create a similar document after the translation, as was loaded from the start. So a PDF original can end up as a PDF target, in the new language, as an example.

It requires some skills by the project manager to operate this tool, plus often several other tools for task/project management and QA.

Translation

The core activity, but still just one of many. Sometimes a project is too big for one translator to do it at the required time, and it can then be split into several parts, each translated by their own translator. Later, the project manager will gather all the parts into one project again.

The translator will often be given a relevant translation memory and termbase for the project, included in the CAT project file package, but not always. Very often, these are missing, and the translator will then need to spend time on research — to find out what this particular client usually translates a certain term into, or what translation the specific business area most often use.

The terms can vary a lot — many nuts and bolts and other technical details have very many different names, and each specialised business, or their customers, will typically use their own set of them. Hence, the research for terminology can be quite time demanding, especially if the business is unusual for the translator or if the source document is less well written.

For translation agencies, it is often a hallmark of quality that their translations are “consistent”. This sounds like common sense, but isn’t. A certain word in one language may be translatable into a certain word in another language - but there can be situations where that will not fit, because it cannot be said that way in the target language. So, if the agency insists that a term is translated the same each time it occurs, it can lead to clumsy or outright wrong translation.

A requirement of this kind often comes from the end-client, and the agency is just the messenger.

The translator will often have to use the correct CAT tool, as decided by the agency or dictated by the specific projects needs. In some cases, the tool is free for the translator to use, but it happens that no CAT tool is used - that the agency or end-client want the translation to be done in-line in such as a Word document.

All of this requires from the translator to know, own, and maintain a large toolbox of different software and skills. It has a price too: the most popular CAT tools are quite expensive.

There will often be communication with the project manager and QA, but rarely with other parties in the project. At times, some additional information about the translation, the involved products or services or whatever is the topic of the translation, or about the end-client will be provided to the translator, but not always. In fact, the lack of context and relevant information can be a big problem when trying to do the best possible translation.

Proofreading 1 + 2

Even though this step is often omitted, as it costs extra time and money, a proofreader most often will be able to find different kinds of non-trivial errors in the text, an occasionally some trivial ones as well. The text can become better with proofreading, and if the highest quality is required, doing it twice after each other by different proofreaders will help.

The non-trivial errors are often a matter of preference, but they can include such as what “sounds better” or “is more typical for the target group” or similar. There can be logical errors as well, where the meaning becomes wrong due to the use of double negations or other complexities of the language, and a proofreader can simply stop whenever something is not clear and think about how this may need to be adjusted.

The trivial errors are such as the lack of capitalization of a word where it should have been, or a list with a mix of commas and semicolons after each line in the list, rather than a consistent formatting.

Some texts can be quite complex, especially if they have a complex layout, so that even the formatting tags and similar can be subject for proofreading.

Linguistic Quality Assurance

The LQA may consist of several different activities, but most often it is about using a dedicated QA tool for checking the translation. Some CAT tools have this built-in, but there are several external tools that can be used as well - or, indeed, the QA tool from another CAT tool, which is quite common.

The QA person will load the project that contains both the original text and the translated one into the QA tool — it will then analyse the translation and the target text in regard to several chosen areas of linguistic quality. Spelling, punctuation, and similar are obvious, but also consistency both ways, so that identical source segments are translated the same each time and different source segments are not translated into the same target text. There are very many possible checks, including the verification that no non-translatable terms have been translated, and that the required termbase has been used. The QA tool will also find excessive spaces or duplicated words, among many other typing errors.

A report will then be made and typically, it will be fed back to the translator unconditionally. Such a report can contain very many false positives, and the QA person will then bi in a dialogue with the translator to find out what needs to be corrected, and what not.

Finally, the QA person will often have to apply the changes specified by the translator to the project files.

Desktop Publishing

While not always needed, some translation projects are required to deliver a ready-to-use document in the correct format.

DtP is the process of setting up the text correctly. The process was once known as page-setting, but with increased features in PC programs, the process became bigger and a DtP person can do everything from raw input text and images to the ready document in one application on the computer.

However, it can take some time to puzzle everything in place - especially, because languages do not take up the same amount of space. Some languages will have longer phrases than others for the same meaning, but it can vary, so even a “short language” can have some longer phrases than the source language. Whatever the case, even with an original document that has been formatted correctly, it is most often not possible to simply replace the source text with the target text - some adjustments are needed.

Often, there will be text in images, and this requires new images to be made.

There will often be questions and communication back and forth to clarify what is correct to do, as the DtP person often doesn’t know the target language. Such as word splitting typically causes problems, and the same when, e.g., words to be placed in the header line of a table are too long - how can they then be shortened?

The project manager may be able to help, but often, the translator will be needed to assist as well.

Post Layout Review

On top of the first round of DtP work, there will be a need for a linguist, perhaps the original translator, the proofreader or someone else with similar language skills, to visually check the document for wrong word splits, missing commas, or other things that can be fixed by the DtP person.

As the end-client often want a textual translation back as well as the formatted document, the linguist will need to update the original project file or give input to the project manager in another way, typically through editing a bilingual file in Word with track changes switched on. Then the project manager will key in the changes into the project file.

In a PLR process, the linguist will, hence, typically have the original document, the draft translated document, and a project or a bilingual file open, all at the same time, cross-checking and updating, making notes in the translated document (for instance as comments and highlighting in a PDF document) — and providing additional comments separately, for instance by email, to the project manager.

All the additional tasks

Apart from the administration that the involved parties will need to do, such as reading tasks descriptions, registering time, managing files, etc., there translation memories and termbases are also — most often — needed. But an end-client having many translation tasks, or an agency that often works for the same client, may have such files ready.

It is very rare for agencies to provide termbases that were bought by third-parties, even though these do exist in the market. Such carefully made termbases are more often used by translators who work directly with end-clients, are managing the projects themselves, and can see an advantage in buying these, rather than creating them.

But it is perfectly possible for a translator to create a termbase, and those who mostly work with clients in a specific business area will often do that. It can save them time and increase the quality of every project.

What this all means

Knowing what happens when you push the button on a translion agency’s webpage, requesting a translation to be done, may help in understanding how a certain amount of time is needed, and also why the cost isn’t just a function of the number of words.

First of all, the more activities, the more time will be consumed. Secondly, the higher the requirements, the more complex will the project be - which will add time and costs to the project.

If you work directly with a freelance translator, they may need to do several of the described tasks.

It is best to let all of this happen at a reasonable speed without trying to push the limits, especially if you are looking for a high-quality translation, and it is best to not try to bargain about the price, as this means the translator will have to try to save time on some areas, to end up with a reasonable average hourly rate for the project.

Best of all: have an open dialogue with the translator about wishes and needs, take in the input from them and expect that they are not just trying to earn extra money — in fact, most translators are very logical, analytical people who speaks the truth when they give estimates and suggest prices.

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.