Introduction

As a developer you can, and most likely will from time to time, be forced to create
customer documentation. It doesn’t matter if it will be in electronic or paper form. In
creating specific applications for concrete customers you will have do all the text writing
up until the final print. Developing general products for thousands of customers will
probably prepare a base that will be given to graphic professionals. In both cases it can’t
be bad to know the minimum about typing and documentation rules. Some points may be
too simple but there are people who do not know about them.

The Editor
The first problem you must solve is choosing the software for writing your
documentation. If you have no serious reasons to, then please do not use Developer
Studio or similar. Our editor software has to be able to work with paragraphs over
multiple lines. In a programmer’s editor you will end every line with a special end-of-line
character. Removing them makes everyone who will follow after you nervous and they
will need reformat it. (The possible exception to this rule can be internal source
documentation generated directly from sources, maybe driven by special comment marks
inside them.)
The editor has to know how to work with, or export to, common formats, such as RTF or
HTML for electronic help files. For Visual C++ you can look at the Scribble tutorial
Help. The program resource ID defines are in RTF stored in footnotes marked by #
characters. Maybe you will use more sophisticated help creation software, possibly with
its own file format - maybe HTML. It seems HTML based help, mostly in compressed
form, is slowly replacing classic .hlp files. You can find some good articles in the
codeproject.com or codeguru.com help sections. Through the use of appropriate file
formats it is possible to present more than simple text information, but do not expect the
that after importing the text from your office editor to your documentation software that
the format will look exactly as you originally intended (and rarely does anyone actually
want this). Because of this there is no sense in playing with formatting details. Of course
it is possible to create usable documentation fully in an office editor only.
When you create help files your software has to know how to work with hyperlinks. If
you want use the same document for hardcopy manual creation do not forget to remove
or hide the hyperlink underlines before printing. One simple method (if you don’t have
complicated documents) is to make a copy, then Select All, set No Underline and Black
Text, and then print. Generally the printed manual will be something a little bit different
to online help. Let’s look a little closer to this:

Starting
What we will talk about are recommended rules for readable document creation. We will
not speak about contents but form. This form, with platform limitations, can be used for
electronic help files too. All rules are not set in stone but are guidelines to help your
readers. Most of rules are tried and true, some of them have been modified over time.
Today everyone can easily and quickly write and print what he or she wants. Many
people think all that a publishing program can do is right and proper, and so they use all
possibilities and formatting that is available. Because of this some documents are simply
a list of installed fonts and several pieces of graphics, forcing the reader to spend time to
find the usable information buried under all this.

Main rule: Follow your grammar

Here I can’t specify details: it’s something that differs by nation or region (and you
already know that from school). As an example here is an English sentence:
“It is 1,234.5”, he said.
Transformed to, say, German typing rules this becomes:
„It is 1 234,5,“ said he. (See comment).
See http://www.fontsite.com/Pages/RulesOfType/ROT1097.html for rules on using
quotation marks.

Space
Use one space between two words. You will often get two spaces when you import or
paste from the clipboard. When you have simple text in one line (i.e. alphabetical
characters) all simple spaces between words have to look to be the same width. Many
editors know of so called solid (non-breaking) space used to keep words together (in one
line) but some of them use it not as spaces but characters (fixed width). In combination
with justified paragraph alignment (see the next section) it looks a little strange. (Btw.
really were times when was wanted all characters changed their width, not spaces only.)
There are more space types - especially in width. You, as a technician, can simply ignore
them (if your grammar does not define them strictly). If you want to play with than use
predefined width or thin space type and not combination of more than one. Some spacing
problems were fixed by font authors. Take for example the ellipsis character (…) which
today replaces three dots (originally dots with thin spaces between them). Putting spaces
before and after special characters like ‘%’ or ‘…’ and words is language, and in many
cases, content dependent. For a long time some (especially non-english) grammar and
spelling checkers would underline them.
Do not start a paragraph with spaces - there are more correct ways (setting the indent
through margins or style sheets) to indent its first line.

Paragraph
As we already seen a paragraph has to be written as floating - with one end of paragraph
character at its end. You can leave line breaking to the editor, especially when making a
base for others to work on after you. We recognize four base paragraph types by
alignment: left, right (not common, though Middle East readers may protest), justified (to
both sides) and centered (for us, if it is used at all, mostly in titles). The first line of each
paragraph is usually indented in order to visually separate paragraphs. A classic (central
Europe experience here) form is that when a paragraph uses 10 point text size, to have a
10 point indent (square) or a multiple (15, 20 or 30 pts in our case). When I look at style
templates for most common office applications they ignore this and use 36. It’s not
wrong, just different. As we said - our rules are not law and can differ locally.
The next old rule talks about choosing the indent for basic text. It’s good to use the same
indent in the entire document, and not have it depend on the current text size. If you have
notes with smaller font sizes use the same indent as your basic text. In the good old days
the (left aligned) title and first paragraph directly under the title were not indented. For
hand written documents it was a natural left alignment. For classic books the (fully)
justified text gave the ideal of an equal-gray page. When I look at today’s computer
literature it’s usually zero indent with an empty line (or extra spacing) between (left
aligned) paragraphs. A similar situation, because of limitations, is found in HTML and
email. Today the most forgotten rule is about the last paragraph’s line: it must not be
shorter than then alignment and if it is longer than line-length minus the indent it must be
justified. Following rules like this now needs manual work (or a script to be run) in most
editors today. When you look at another available paragraph formatting options you can
see options such as: “keep with next”, “page break before”, “keep lines together”, “don’t
hyphenate” etc. All very good for titles, as it is not nice to have a title at the bottom of a
page or divided to two pages. The same can be said about (word) hyphenation in titles.
With widow/orphan control the convention is, when possible, to not start a page with the
last (unjustified) paragraph’s line - the orphan. A little less unfortunate is to end pages
with the first paragraph’s line - the widow. Many languages commonly limit the number
of hyphenations (word-dividings) at line ends, often differently in simple and column
layout. In some of them the divide can be not be a simple regular endofline-/startofline
(for theoretical endoflinestartofline example word). There is the classic german “sugar
cutting” example: zucker -> zuk-/ker.

Font
For the final output you have to select fonts. Using less fonts and their variants (italic,
semibold, bold; uppercase or capitals) makes the text more readable. With too many
highlights the reader loses orientation. Where possible use true fonts, not software to-bold
or to-italic emulation (and degeneration). Eliminating comic, old style caligraphic and
symbol fonts means we can divide usable fonts into serif and not serif (sans serif) groups
(sorry to those professionals reading this!). Classic members of the first group are Times,
and the second group Helvetica. Most of us use their Microsoft variants Times New
Roman and Arial. Non-english users especially know their sub-optimal quality and
strange kerning pairs. In most cases a Times variant is used for base text and Helvetica, in
a different size (possibly semi-bold), for titles. When you create documentation for an
aggressive environment like industrial machine handbooks you may use (more rounded)
Helvetica as the base text too. In one document do not combine similar (from the same
group) fonts like Times and Times Roman, it doesn’t look good.
Common paper book color is black on white. Who wants read green text? In electronic
documents try look at possible settings. Not everyone must have (or will enjoy looking
at) your color schema.
Conventional basic text size is about 9-12 points. For children, old people or people with
disabilities you can choose a bigger size. The same for an industrial environment. If you
will combine letters and numbers try to find a font where the small L and number 1 (one)
look different. Titles have to be with a bigger font, maybe in bold, but keep inch high
titles for newspapers only. Again - twenty title levels with different styles are not
efficient.
In paper form do not use underlined text. There are another traditional and more effective
effects for selection. Leave the reader and their pencil do any underlining necessary. To
highlight sections of text you can use a different text spacing (be careful - it has to make
sense in the text flow to do this, especially do not attack normal space width), italic or
semi-bold. If possible do not combine semi-bold and bold, since the reader needs to stop
and think what is what. If you create a table of contents it can be in the same font like the
base text, or possibly a little bit smaller. Page numbers in our case can be in the base font
or little smaller. Placing them into book break leave for poetry, in technical literature they
are for searching. If you are displaying source code use non-proportional (fixed width)
fonts, since it should look like what you see in your programmer’s editor. If you place
source code directly into a paragraph then keep a proportional font but with a readable
marking (e.g. italic). In technical documents do not use special effects like ligatures or
drop caps. If someone will read from begin till this he will surprise me.

Summary
I mentioned some basic and I hope general rules. Keeping them simple will help you
think about what you wrote and not how it is written. These and many other rules can be
found in many publishing-software options. Some of the terms are parameters for text-
API in OSs or publishing systems.
There are many, many other rules that can be looked at, but there is a point where an
introductory article must stop and make way for a more comprehensive article.
If you plan own solutions (but ask yourself: why?) try to look at it more generally before
you start. Solving rule conflicts by not breaking other rules, especially when working
with aesthetical priorities, is still hard work. You can leave them to editor. It’s not
expected that you will know everything that you must do, but do ensure that you follow
the most important rules. They can at the start look strange but most of the time come
from long years of practical experience. You can get more of a feel for this from bigger
and more comprehensive books and articles and it can also be good to consult
professionals. You still can find some of these that know more than how to simply import
and print files.