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
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
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.
No comments:
Post a Comment