The World Needs Technical Writers

We are lacking something - ever since we fired all the secretaries

Photo by Clayton Robbins on Unsplash

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.