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.
Beginner's English links
If you interested in and want to know more about this then you can start at
www.lyonsdigital.com/guide/index.html
for basic vocabulary. There is a great article on Typography at http://www.macworld.com/1998/01/macuserinsert/4132.html. A very nice and illustrated half-tutorial article can be found at
www.adobe.com/products/indesign/pdfs/idsn15typography.pdf
(link from www.adobe.com/products/indesign/techpapers.html).
Here Adobe wants to show that its product knows all or more than you (as a modern typist)
can imagine. Maybe I didn't read close enough, but I do not remember any mention about automated
rivers elimination (rivers are +- vertical white lines created by spaces under themselves in
following lines) but being realistic who today plays with them? When you visit
http://www.fontsite.com/Pages/Archives.html (see Part I-VII links) you will get list of recommendations. Some of them I compiled to this article. Maybe it's
better you don't worry about cases 4-7, 10, 12 and 13. Until you are sure it's better to
not play around with font settings - simply assume the font authors know what they were doing.
If you know about more usable links please append them as article comments. For example, it
may be interesting to know something more about Japanese problems.
