Posts Tagged “documentation”
May 30, 2020
On Friday, my employer had a “learning day”. Among other things, I followed a typography video course called “The 33 Laws of Typography” by Jill Butler. I liked it a lot and I took notes so I could actually remember the conclusions of the course, so I’m publishing them here in the hopes that they will be useful for other people.
This will be long!
There are five categories for the 33 Laws of Typography:
- How to Format a Document
- How to Format Large Bodies of Text
- How to Format Small Blocks of Text
- How to Use Punctuation Properly
- How to Choose Typefaces
How to Format A Document
Distrust default software settings
In particular, Typeface, Type Size, Line Spacing, Margin Sizes, Text Alignment.
Ensure good contrast between text and background
To ensure text legibility. Reverse type (light text on dark background) is fine for small chunks of text, but have to be careful with thin strokes in the font (sans-serif tend to work better because of this, and extra letter spacing and line spacing).
Complex backgrounds can be almost impossible if there are different colours in it (impossible to have enough contrast with all parts of the background). In those cases, use a box with a single colour.
Avoid chartjunk and pagejunk
Chartjunk: excessive and unnecessary use of graphical elements in charts and graphs.
Pagejunk: excessive and unnecessary use of graphical elements on pages. Usually boxes, shadows, and rules.
Watch out for fancy, thick, and double rules in boxes. Also small margins in boxes… and pages.
Enforce consistent style within a document
Use software styles, or CSS on web.
Maintain a visual hierarchy
Document title, Level 1 Headings, Level 2 Headings, Body Text, Image Captions, Headers and Footers.
Plan which elements the document will contain so you can make design decisions about the hierarchy.
Group related page elements
Gestalt’s Law of Proximity, eg. having headings closer to the body text (or subheadings) than whatever is before them, so they are visually grouped with the text.
How to Format Large Bodies of Text
Set printed body text from 9 to 11 points
9pt to 11pt on print, 12px to 16px on web. Font size is measured from the top of the ascenders to the bottom of the descenders! That’s why different fonts look small or big in different fonts.
Set body text 2 to 3 alphabets wide
Too narrow is bad because all the eye jumps (and possibly jagged lines when left-aligned, or “rivers” when justified), too wide is bad because it’s hard to read long lines.
Should be 52-78 characters wide. For fancy typefaces or reverse type, 52 characters or a bit less is good. For justified text, better to use 78 characters or more.
Favour flush left, ragged right body text
The problem with justified is the potential “rivers” (horizontal gaps that sort of align). Shorter line lenghts are worse for justified text.
Flush right is ok for figure captions, attributions, and such.
Center for document titles, formal invitations, etc. It gives the document a conservative moods.
Separate sentences with one space, not two
Two spaces are a convention of the past, don’t use it. They produce big spaces that can be distracting.
Don’t allow less than 7 characters on a line
For example, at the end of paragraphs. Doesn’t look nice, and it wastes space. The goal is to keep visual balance. Ways to fix this:
- Widening the text block, to make the text reflow.
- Changing the font size.
- Edit the text itself (usually the best)
- Use a “soft return” (Shift-Enter) to force the end of a line.
- Use a non-breaking space so that some words cannot appear on different lines.
This is not just for body text, also for headings and such.
Avoid bad paragraph breaks
When paragraphs break in between pages, don’t leave a single line in either page (if it’s part of a bigger paragraph; single-line paragraphs are fine). Of course, titles that go with the paragraph should go together with the first line of that paragraph.
It creates visual imbalance and makes the point of the paragraph kind of moot because the text is not together. Solutions:
- Edit the text
- Tweak the “keep options” in the software you’re using (how many lines of text have to be kept together)
- Change the text box width / height
- Tweak the space that surrounds headings (if there are many)
- Add image or pull-quote
Avoid line-breaking hyphens
The automatic ones added by the software when a whole word doesn’t fit in the line. They are ugly and they break concentration and reading rhythm. They should be avoided.
If you must use them, don’t ever hyphenate any headings or proper names. Don’t allow more than 2 consecutively lines ending in hyphens in a paragraph. Don’t hyphenate URLs or email addresses. Don’t allow your software to make all the hyphenation decisions (you can control consecutive hyphens in a paragraph or turn them off).
Signal new paragraphs once, not twice
Don’t both indent the first line of each paragraph and add vertical space.
Never use spaces for the first line indent, always a setting (1-2 times as wide as the type size).
For vertical space, use space before or space after, not both. It should be 50-80% of the type size.
Break up large blocks of text
Too much of the same, full text page becomes dull and uninviting. Some possibilities:
- Drop Caps (drop together with the second/third lines of text) or Initial Caps (just big letter, same baseline as the first line of the paragraph).
- Rules: for headers, footers, and sometimes some headings.
- Pull quotes: highlighted quotes in a box, separate from the rest of the body text.
- Whitespace: big margins to lighten up the feeling of the page.
- Graphics. Only if they are good quality. They are not required.
Don’t add more than needed! Just enough to solve the problem.
How to Format Smaller Blocks of Text
Emphasize 10% or less of text
Emphasis should be limited so it stays effective. Both things like bold and such in body text, and font sizes and colours in business cards and such.
Avoid All Caps and Underlined Text
Limit their use to titles and headings. Underlines should be avoided, use italics instead. You can use rules for headings, never underline. Some good ways to emphasize text:
- Italics - should be used for book/film titles, too!
- Small Caps
- Different typeface
- Spacing - doesn’t work so well in body text, but it can be very effective in business cards, posters and others
- Size - same limitations as above
- Colour - be careful that the emphasis is not critical to understand the text
Choose one technique and use it throughout, don’t oversignal (use more than two or more techniques at the same time for the same words).
Set Acronyms and Initialisms in Small Caps
Acronyms are pronounced as words, initialisms are pronounced as each letter separately. These in all caps take over the document visually.
Small Caps (uppercase characters that are around x-height tall) look much better. A tiny bit of letter spacing makes acronyms look even better. Choose a type family that includes small caps typeface.
Hang punctuation in small chunks of text
Hang punctuation means that eg. the opening quote is outside of the left margin. Also final periods being outside of the right margin, when right-aligning text. Applies also to quotations, headlines with question marks at the end, etc.
In body text, punctuation is usually not hung, but it’s important in bigger font sizes and such.
Hang bullets and numbers in lists
It makes a difference when the items have more than one line. Numbers should be aligned in the “decimal point” (even if it’s not visible), ie. to the right.
Learn to use “tabs”: left-aligned, right-aligned, center-aligned, decimal-aligned.
Avoid Bad Line Breaks
There are two bad breaks: visual (visually disrupt the flow, eg. in left-aligned text, producing bad ragged edge) and contextual (sentences are broken so words that should appear together, don’t; it makes the reader go back and re-read).
Watch line breaks with URLs and email addresses, which should appear in full in one line whenever possible. How to fix?
- Edit the text
- Change text box width
- Change the size of the text
Use Symbols and Special Characters as Needed
Registered trademark, degrees, etc. Look for and use the proper one. Character map apps on desktop, character entities on web.
Not all fonts contain all these characters, so make sure that the font contains what you need, if you know you will need “special characters”.
Use Proportional Oldstyle Figures in Body Text
Numbers with digits that take different horizontal or vertical space. These are great for body text, but the “lining” (the other type, all digits are equally wide/tall and have the same baseline) is better for comparison and data tables and such.
There are tabular and proportional, too, so four types total (2x2 types):
- Oldstyle proportional: for body text
- Oldstyle tabular: for uppercase text
- Lining proportional: for fancy table data
- Lining tabular: for data tables
OpenType fonts are the ones that have all these combinations.
Adjust Leading and Kerning for Large Text
Leading: amount of vertical text from baseline to baseline (line spacing). Default is usually 20%.
Kerning: horizontal space between certain letter pairs (not the same as tracking/letter spacing).
Why do we need to adjust leading? For body text, default leading is usually fine. Large text usually needs less leading, and even less if there are few descenders!
Kerning is also usually fine for body text. In large sizes, sometimes kerning needs to be adjusted.
Verify Software Alignments Optically
Sometimes alignment is mathematically correct, but visually wrong, because some parts of the text, especially logos and such, are “visually lighter” so they should be taken as taking less space.
How to Use Punctuation Properly
Connect thoughts using em dashes
When to use em dashes when you don’t want a comma, but not sure what to use instead. They can be used to:
- Add emphasis
- Indicate long pauses and interruptions
- Indicate abrupt changes of thought
Full spaces between em dashes is wrong! But depending on the font (if the em dash touches or almost touches the letters) you might need to use a “thin space” (1/5 of an em wide). If you don’t have the option to add a thin space you can enter a space and use a smaller font.
Show Ranges Using en dashes
In between a hyphen and an em dash. It’s used for:
- Show ranges of time, duration, or distance
- Join words when at least one word is an open compound (New York-New Jersey Border)
- Join hyphenated compounds (post-Jacksonian–pre-Nixonian politics)
Don’t add full spaces between en dashes, but depending on the font, size, etc (if the en dash touches or almost touches the characters), you may need thin spaces.
Clarify and Improve Readability Using Hyphens
Their usage can be confusing. It should be used to:
- Improve readability and clarify meaning (five-dollar bills vs. five dollar bills)
- Joining a letter with a word
- When using the prefix “Re” to mean “repeating”, “again”
- Joining a prefix with a proper noun
- Joining a prefix and a root word with repeating characters: ultra-ambitious, non-native
- Joining two words that contain the same three characters in a row, eg. cross-section.
- Numbers between twenty-one and ninety-nine
- Phone numbers and social security numbers
- Joining two last names
It’s not the same as the minus sign! Don’t use hyphens for minus signs!
Designate Feet and Inches with Prime Symbols
Prime symbols are similar to but different from both curly quotes, and straight quotes. Straight quotes should never be used! When to use curly quotes:
- When quoting material (quotes inside quotes use the single quotes)
- Single closing quotes are the same apostrophes
Feet and single prime symbols, inches are double prime symbols. Math, music, linguistics and other fields also use prime symbols.
Replace Missing Characters with Apostrophes
When to use apostrophes:
- Gone Fishin’
- Bread ‘n’ Butter
- For decades, you say ’40s (missing “19”): the “40” doesn’t own anything
Careful with “Bread ‘n’ Butter”, because by default word processors will typeset the “n” in single quotes (the first one will be open, not closed).
How to Choose Typefaces
Limit typefaces to two per document
If you are not a professional, using more than that makes it too easy to become messy. One serif and one sans serif is a good place to start. Sameness competes, but differences highlight and contrast. If the difference is not big enough or doesn’t add anything, one typeface is much better.
Use typefaces that reinforce a document’s mood
It’s easy to feel overwhelmed by the choice of fonts, and you end up always choosing the same one. To help you choose, always think about the mood/personality of the document you’re creating.
Choose Serif or Sans Serif, based on aesthetics
For type size larger than 10 points, there’s no difference in readability between the two types. For smaller type sizes, sans serif have an edge, especially on computer screens (they are simpler).
For reversed text (white over black), medium-weight, slightly larger sans serif work best. You can use serif, but they have to have thick and uniform serifs: no “delicate” serifs!
So, in general, focus on the mood/personality and aesthetics first. Sans serif are a bit more modern and contemporary, and serif a bit more conservative and traditional.
This is it! I hope it was useful. I really recommend the course if you are interested in the topic: it has a bit more context and of course the visual examples and explanations that you lack in this summary.
Nov 28, 2008
After a couple of (unrelated) recent events, I remembered that some/most people use some desktop “word processor” for writing and maintaining documentation. After years of working with Wikis for virtually all documentation, I have to say that I don’t understand why people still use those dinosaurs. Using a word processor for documentation feels so nineties.
When working in technical teams, I think the advantages of the Wikis are amazing:
You know you’re always reading/modifying the latest version. Uploading to a central server or a shared folder, although theoretically possible (and I’m sure some people do), I don’t think it works as well.
You can link all content to any other content (and if you keep all your documentation in the same Wiki, you can link to other project documentation or general company/team guidelines or conventions, for example).
You can keep bits of documentation that don’t fit in a standalone “document”, like collections of small tips, lists of things to take into account when you do this or that, checklists, configuration/code snippets and examples, journals, etc. And of course link all that to any other part of the documentation, as stated above.
You think “globally”, in terms of the content, not in terms of “documents” that are (usually artificially) independent from each other. Also, it’s mentally cheaper to browse through wiki pages than it is to browse word processor documents, so the documentation is more visible and more used.
You focus on content, not on formatting or the way things are presented. It’s also easier to keep the same consistent look and feel for all your documentation, if you wanted to change it.
As you don’t have “documents”, just “documentation”, people feel free to edit and update it whenever is necessary, instead of feeling the need to ask the “author” of each document.
You don’t need any special program that might not be available in all platforms, or at least not interpret the document in exactly the same way. It’s also easier to access it from other computers.
Documents don’t get lost or become obsolete because of the format.
You usually get revision control for free (revision control that makes it trivial to see the whole change history for the documentation, review which exact changes some person has made in a given moment, etc). And if you’re using a Wiki that doesn’t support version control, you should use a different Wiki
Of course, I’m not saying Wikis are the perfect solution, let alone independently of the team, company, project and context you’re using them in, but I think in general they are quite superior as technical documentation repository for a software development team.