The tools of the trade - on the technical aspect of writing, part 1
The (less than) fascinating journey through writing and editing a piece of text, put down by the technical writer adept in documentation, but also in fighting evil mutants, spaceflights and reporting local events.
# What all this is not about
Writing is one of the basic skills we need in today’s societies. Even though it is less and less necessary to be able to write by hand — quite honestly I see little use for it other than signing a deal or a speeding ticket — the ability to write is crucial in both private and professional environments.
This series of blog posts is all about the bare bones of the writing process, which consists of tears, curses, coffee, more tears, soul-voiding struggle and more curses. It may just as well be a novel, but what we are dealing with is basically the same for an owner’s manual preparation, for a short piece of breaking news and software documentation. Things need to be done and there are certain ways to do certain things that produce results.
This is the story about the tools of the trade, which I will tell with CKEditor 5, an advanced WYSIWYG text editor, in mind. It is not just because I do work at CKSource and feel somehow obliged. I didn’t really watch the soap operas I worked at twenty years ago. I just use the editor on a daily basis doing my job. It would be strange not to use the product I help to develop, especially if the product is good. And by using something, you grow to like and know the product, which is generally good for somebody writing technical documents for a software framework.
# Essential formatting features every writer should know
There are certain basic tools a technical writer or journalist needs to successfully perform the process of transferring a text (be it a journal entry or an article, a passage in a manual, or even a novel) from their mind into a more easily accessible form of a digitized text. Aspiring novices and laymen tend to waste plenty of time on things that are utterly meaningless, like choosing the right font for a text that has not been well sketched out yet, not to mention typing it out. And yet some come in handy even if you leave that work to some other professional. Let’s call them the apocalypse riders for the purpose of fun.
# Font size
The size of the typeface. Well, this one is tricky. Font sizes are hardly used for purposes other than text structure, they are sometimes (though rarely) employed in the text body. This kind of decision is usually taken out of the authors’ reach by the news portal editor or by a documentation site designer. Let us, however, add this to the editor toolbar. Yet this is often a personal decision or preference, much like the one we make while using e-book readers. Sometimes they’re fine to read with a 12 point font but — especially during dim winter evenings after a long day of work, sitting by the fireplace — much larger fonts are needed for comfort and ease of reading.
# Font family
Typeface is basically expendable during the writing itself due to the very same reasons mentioned above. You don’t get to choose font faces for articles, novels, manuals or brochures. And it’s not your responsibility at all to format the font face. This belongs to other people; it used to be the printer (the person that put together fonts and operated the press, not the noisy device you keep on the window sill that produces colouring pages for the youngest one), but nowadays it would fall more into the hands of a webmaster or a DTP operator. But there are still fonts good for print, fonts good for screen, and fonts that are easy to read quickly and carefully. And there are personal preferences, again. So let us have the font face dropdown in our word processor to make our writing and editing process the most comfortable and efficient. Because, why not?
# Headings
Whatever we may say about DTP and putting a website, a book or an article together, it must be delivered in a structured, readable form. We may not need subheadings for a news piece about the latest Star Wars TV series, but a critical article about the best Star Trek movies will need them for sure. And a novel about a cunning, axe-wielding warrior and her brave mount of a giant cat in the Southern Continent will probably need chapter titles and a table of contents. Furthermore, sections describing all the separate aspects of a file uploader will surely look better when they stick out from a wall of text. This is what headings and subheadings are for. Put them on. Give your writing a structure that the user — the reader — will follow. Lead them down the path of knowledge. Even if this is just the question of which button does indeed deliver a large black coffee. Not everyone likes a frappuccino at seven in the morning, right?
# Formatting style and more
The size and typeface are important, but they wouldn’t be the first ones to come into mind of a writer, to be honest. There are styles shared across all types of text regardless of these — the formatting basics. They are rather simple - all you need is a plain face, a bold one and a cursive one and this is about it. Sometimes there is a strikethrough or underscore, too.
There are also the block formatting styles, like the block quotes that are just so perfect to highlight a software solution or special feature of a new meat grinder or the most important question of do we have anything to answer in this news headline at all?
# More useful functions to employ
Even though basic formatting features will mostly be enough for most tasks, there are some more that writers of all sorts might want to enjoy.
# Undo / redo function
There is one more, a fifth apocalypse rider in this wild bunch, although we would consider it more of an anti-apocalypse rider. It may even not be necessarily represented with a toolbar button as it has a handy, widely recognized keyboard shortcut. The undo function and its twin sister the redo function. Together they are one, the bringers of joy and relief.
# Color formatted text and backgrounds
To be honest there is more to formatting than just those basic five. There are also things like text colors, which are useful if you create some kind of subatomic schemata that needs to be broken down by color to differentiate between the covalent and regular electron shells.
# Left, right, left!
I could go on enumerating them but it would be pointless, especially in the face of my previous statement that the big ones should be enough for most professional applications. But please note there is also the alignment feature that will let you put the asterisk in the middle of the graphic break. Having the text justified evenly looks neat. Moving all the content to the right might be useful for special-purpose writing like invitations, leaflets and so on… We are all people, and we all like our shiny toys.
# What’s next?
This is it for today, but this series is far from over. Drop in for part two, where I’d like to invite you to explore some less obvious and more intricate features, functions and available solutions to less expected problems.