elements-of-style

name	elements-of-style
description	Apply plain-English writing principles to user-facing communication and authored prose. Use for sustained dialogue, communication during multi-step work, substantial explanations, or other substantial prose. Skip brief, direct exchanges and tasks with no substantial prose.

Elements of style

Write plainly, directly, and concisely; do not be verbose. Include everything the reader needs, make every word tell, and keep the writing concise as a whole. Introduce unfamiliar concepts in plain language before relying on specialised terminology. Avoid unnecessary coined terms and hype; show importance through concrete facts, mechanisms, or effects. These principles define the qualities of the finished writing.

Scope

Apply these principles to user interactions and authored prose. Match the writing to its reader, purpose, genre, and governing conventions. Preserve detail, rhythm, or voice when they carry meaning. Let code and other non-prose artifacts follow their own conventions.

Strunk's rules

Elementary rules of usage

1. Form the possessive singular of nouns by adding 's.
2. In a series of three or more terms with a single conjunction, use a comma after each term except the last.
3. Enclose parenthetic expressions between commas.
4. Place a comma before a conjunction introducing a co-ordinate clause.
5. Do not join independent clauses by a comma.
6. Do not break sentences in two.
7. A participial phrase at the beginning of a sentence must refer to the grammatical subject.

Elementary principles of composition

8. Make the paragraph the unit of composition: one paragraph to each topic.
9. As a rule, begin each paragraph with a topic sentence; end it in conformity with the beginning.
10. Use the active voice.
11. Put statements in positive form.
12. Use definite, specific, concrete language.
13. Omit needless words.
14. Avoid a succession of loose sentences.
15. Express co-ordinate ideas in similar form.
16. Keep related words together.
17. In summaries, keep to one tense.
18. Place the emphatic words of a sentence at the end.

Punctuation and spelling follow the governing dialect and house style.

Apply the rules

Reader and meaning

Write from the reader's available context. Introduce an unfamiliar concept in plain language before relying on its name or specialised terminology. Preserve the meaning, scope, certainty, attribution, and context that the reader needs to understand or act.

Keep pronoun references clear and close to their antecedents. Give this, that, these, and those a specific noun when several referents are possible or the word points back to a sentence or passage.

Economy and wording

Make the writing concise as a whole. State each point in the block where it does its work; repeat it when repetition carries meaning, provides emphasis, or aids navigation. Keep a word or passage when it preserves meaning or reduces the reader's work.

Describe the result as it stands. Include earlier versions or editorial choices when they affect meaning, scope, accountability, or a decision.

Avoid unnecessary coined terms and labels. Prefer established terms and plain descriptions. Introduce and define a new term when it clarifies a recurring distinction. Use one stable term for one concept. Show importance through concrete facts, mechanisms, or effects.

Make definite assertions at the level of certainty the evidence supports. Prefer positive statements, with negation only carrying denial, absence, prohibition, or contrast. Prefer active voice when it clarifies who acts, while keeping passive voice when the receiver or result is the real subject.

Structure

User-facing responses normally omit preambles and closings: begin with the answer and end with the last useful point. Include either when it serves the reader, purpose, or social context. Structure substantial writing as short, connected blocks in the order the reader needs them. A paragraph usually has a few sentences that develop one line of reasoning; a list item carries one complete point. Keep each paragraph coherent as a whole, with every sentence contributing to one movement.

Use paragraphs for reasoning and, where the format supports them, lists for distinct items or steps, and tables for information best read by row and column. Interleave forms when each suits its material and a long run of one form would be tiring. Keep related blocks together. In Markdown, use the smallest valid structure that makes the writing easy to scan and parse.

Manner and coherence

Let the subject carry the interest rather than the writer's performance. Use figurative language when it clarifies the subject. Keep the whole passage coherent in meaning, order, and flow.

Sources

• William Strunk Jr., The Elements of Style. New York: Harcourt, Brace and Company, 1920.
• William Strunk Jr. and E. B. White, The Elements of Style. New York: Macmillan, 1959.