6. Transitioning from creative to technical writing

Hardly ever does one start a technical writing career without previous writing experience. While it is not uncommon for project managers or even developers to take this step, it would probably be true to say that creative writers, copywriters, and translators are prevalent. Coming from a previous, established writing background is, of course, a great aid, but it can also be a serious setback. This is because technical writing has little in common with writing fiction for entertainment or even factual non-fiction or essays.

The most important difference is the plain language discussed and described in this paper. It is worth noting that certain parts of this work do not follow the advice of using Simplified Technical English (STE) or plain language at all. This is because some chapters must evoke the readers’ interest. Practical solutions, however, such as five steps to plain language given previously, follow their own advised solutions. Easily switching between these two “modes” of language is a skill that takes considerable time and a lot of hard work to achieve.

At first, while writing technical documentation, I tended to make the language “nice”. I wanted the reader to find pleasure in delving into the secrets of the software product we were describing. However, reading pleasure is not sought after by the readers of technical manuals. This is wrong. Users need answers. Users want facts. The target audience demands clear and concise instructions. Solutions, tutorials, demos, and code snippets in the installation sections are what people want.

As mentioned before, it took me time to learn. Gone were the adjectives, the passive voice has been reckoned with, and chopped into pieces were the lengthy sentences with the unmistakable melody of American English. Away with ye! After more than two decades of writing pretty stories, I had to restrain myself and spit out precise, concise, factual, and actual data. The resulting frustration was described (even if in a semi-humorous way) in my essay titled Tech-writer lamentation: You is the because.

The two greatest aids in this somewhat sad but necessary switch were reviews from an experienced mentor and software solutions. The help of an older colleague is always invaluable. First of all, they provide all the onboarding knowledge, such as the application of brand books, preset documentation rules, company-specific approaches, and other regulatory devices. What is covered by these? Mostly the vocabulary, the predominant language variety if applicable (it will be different for the USA and UK, for example), and the preference for certain words and names used to address certain concepts.

An experienced mentor will also review and – at least in the first phase – correct your work and give you instructions and tips on how to improve your writing and where to change the approach to certain types of documents produced. Learning by practice is probably the most superior way to gain new skills, however, a skilled mentor is not always available.

Should that be the case, there are certain gimmicks and software solutions one may employ to aid their daily work. Spell-checkers and language aids are the first that come to mind. Online browser plugins such as Grammarly or Hemingway come in handy. The first one can point out and fix your errors on the go. It can also help set the text tone and approach toward the reader, as well as the language variety. While commercial, it also offers a free version. Hemingway helps to break down and rewrite sentences and passages to make them simpler and more accessible. It, too, offers both a commercial and free version, although the latter is far less comfortable to use than its competition.

If you employ the docs-as-code approach in your technical writing – probably a general standard in software companies – you may make great use of development tools, such as linters and command line tools that can not only point out spelling mistakes but can even be fed dictionaries and rulesets to follow. One such tool is Vale, which can reside on a repository level on GitHub. Attached to an editor, such as VSC, it will underline all words not present in the dictionary. It will also point out language mechanisms such as passive voice if the applied ruleset does not allow them. Such software will often use external standards such as the Microsoft Style Guide, Proselint ruleset, or Readability rules to check the language.

All major popular solutions, such as Microsoft Office or Google Docs, offer basic language tools that can be boosted and expanded with plugins and scripts. Professional publishing and DTP software, such as Adobe InDesign, offer powerful tools that can deal with the technical side of text composition. Employing these in your daily tasks can lessen the workload for both the writer and the reviewer and make the transition from creative to technical writing easier and less frustrating. Having a helping hand, even if it is just an AI-driven piece of code, is always better than staggering up those steep stairs on your own. There are many available solutions, and because we love standards, there are also plenty of them that can be applied in a technical writer’s work. While this is not exactly the place for Linus’ Tech Tips and enumerating writing software, I will mention a few popular plain language standards in the next chapter.