Mark Adler
Writing tips
Planning
Consider:
- what you want to say.
- to whom you are saying it.
- why you want to say it.
- whether you need to say it.
- how to present it (including what extra information might be useful).
- the likely effect on the readers.
Organisation
Organise the document coherently (that is, arranging the contents in a sensible order, clearly and logically divided into a hierarchy of sentences, paragraphs, and — where appropriate — chapters, parts, and so on).
Keep paragraphs short enough to keep readers in sight of the next break. If there is too much material on the subject of that paragraph, consider using sub-paragraphs or headings to maintain both consistency of organisation and brevity.
Consider beginning paragraphs with a sentence that follows from the last paragraph and summarises the current one.
Avoid sentences of more than 40 words and consecutive long sentences within that limit, aiming for an average between 15 and 25 words.
Move from the general to the particular.
Avoid irrelevant detail.
Keep subject, verb, and object close together, and generally in that order.
Keep like with like as far as possible, so that all references to a particular thing or class of things are found together.
Use definitions thoughtfully,
To:
- introduce a short, convenient name,
- explain an unfamiliar expression,
- restrict or expand the usual definition, and
- specify which of more than one commonly accepted definition you intend,
if possible choosing a name that helps rather than hinders the readers' understanding.
Remove unnecessary definitions.
Design
Be consistent in design.
Prefer plain to elaborate design to avoid distracting readers.
Use blank space to:
- make the page look appealing.
- show the relationship between paragraphs, sub-paragraphs, and so on.
- rest the eye.
Use color if it will help (for instance, to make the document attractive or to distinguish certain parts of the text) but remember that a reader might be color-blind and that someone might need to make monochrome copies).
Choose fonts of suitable type and size, especially avoiding text too small for readers’ comfort.
Use the size and weight of the font in each heading to indicate the heading level.
Embolden and italicize for headings and to a limited extent for emphasis (ensuring that no text looks more emphatic than a heading which applies to it).
Separate lists, so that instead of all the items forming a continuous paragraph, each item has its own indented sub-paragraph following grammatically, consistently, and without unnecessary repetition from the line that introduces the list.
Supplement or replace text with tables, graphs, flowcharts, pictures, algebraic formulas, and other graphics to help readers understand your message or to emphasize it.
Language
Adopt as informal a tone as is appropriate in the circumstances (which include the readers’ and writer’s preferences and the relationship between them).
Prefer concrete to abstract language, and explain unfamiliar abstract ideas with examples.
Avoid:
- ambiguity.
- vagueness.
- misleading euphemism.
- over-emphasis.
- language that will cause inappropriate offence.
- superfluous words.
- long, archaic, or unfamiliar words where a short, modern, or familiar word is as appropriate.
- nominalisation (preferring he decided to he made a decision).
- clichés.
Do not confuse readers by using different words for the same thing or by using a word in different senses.
Use active verbs unless there is good reason for the passive.
Express ideas positively rather than negatively where practicable.
Grammar
Write grammatically.
Punctuate normally.
Use capital letters only where standard language requires them (although some lawyers justify their use to flag defined terms.)
Avoid pointless obedience to unhelpful conventions that are not rules (like not starting a sentence with and or but and not ending a sentence with a preposition).
Style
Be consistent in style.
Listen to the rhythm of your text in your mind’s ear and edit to make your writing flow.
Editing
Read draft documents carefully, checking:
- the use of these techniques.
- for clerical errors.
- the completeness and accuracy of content.
Re-read them as often as time and patience permit.
Read as though you were the intended reader rather than the writer. If you are writing for different audiences read with the eye (or ear) of each. Beware linguistic and cultural differences.
As far as practicable, re-read the whole document after any change.
However carefully you have edited on screen, finish by checking the hard copy of any document that is to be printed.
As far as practicable, ask at least one other trusted person to duplicate these steps, as a fresh set of neural pathways will pick up mistakes to which you are blind.
Use computerised checks if they help, but don’t trust them.
Testing
To the extent that it is practicable, test the otherwise finished document for comprehensibility: is the target audience likely to understand it in the way you intended and without undue difficulty?
And more (if only, like me, a little at a time and — too late — when you've retired)
Take into account what linguistics, physiology, psychology, sociology, and anything else can teach about effective writing, in particular how the eye and brain function when we read, how the brain processes language, how different people can differently interpret the same document.
Study rhetoric to make your writing more persuasive.