Skip to content

style-guide.md

Latest commit

 

History

History
117 lines (79 loc) · 5.74 KB

style-guide.md

File metadata and controls

117 lines (79 loc) · 5.74 KB

Style Guide

Use this guide when writing specs, plans, agent instructions, or any documentation.

Core Principles

Keep it succinct and focused. No fluff. Short and to the point. Make every word count. No long rambling documents.

Focus on the minimum information needed to accomplish the purpose and no more.

Trust and empower the AI coding agent who will be executing this.

No concluding errata. Don't add "future considerations," "next steps," "benefits," or "implementation summary" sections. All important future work belongs in the plan itself. Flag open questions at the top, not in a conclusion.

The Elements of Style - Abridged for AI Agents

Condensed from William Strunk Jr.'s public domain text

Priority Order

1. Omit Needless Words

Vigorous writing is concise. Make every word tell.

Common violations:

  • "the question as to whether" → "whether"
  • "there is no doubt but that" → "no doubt" or "doubtless"
  • "owing to the fact that" → "since" or "because"
  • "he is a man who" → "he"
  • "in a hasty manner" → "hastily"

Replace verbose constructions:

  • "There were a great number of dead leaves lying on the ground" → "Dead leaves covered the ground"

2. Use Definite, Specific, Concrete Language

Prefer the specific to the general, the definite to the vague, the concrete to the abstract.

  • "A period of unfavorable weather set in" → "It rained every day for a week"
  • "He showed satisfaction as he took possession of his well-earned reward" → "He grinned as he pocketed the coin"

3. Use the Active Voice

The active voice is usually more direct and vigorous than the passive.

  • "I shall always remember my first visit to Boston" is better than "My first visit to Boston will always be remembered by me"
  • Use passive only when necessary or when the actor is unknown/unimportant

4. Put Statements in Positive Form

Make definite assertions. Avoid tame, colorless, hesitating language. Use "not" as a means of denial or antithesis, never as evasion.

  • "He was not very often on time" → "He usually came late"
  • "did not remember" → "forgot"
  • "did not pay any attention to" → "ignored"

5. Place Emphatic Words at the End

The proper place for the word or group of words you want to emphasize is usually the end of the sentence.

  • "Humanity has hardly advanced in fortitude since that time, though it has advanced in many other ways" → "Humanity, since that time, has advanced in many other ways, but it has hardly advanced in fortitude"

Essential Composition Rules

Make the Paragraph the Unit of Composition

One paragraph to each topic. The beginning of each paragraph signals to the reader that a new step in development has been reached.

Begin Each Paragraph with a Topic Sentence

Enable the reader to discover the purpose of each paragraph as they begin to read it. The most useful paragraph structure:

  1. Topic sentence at or near the beginning
  2. Succeeding sentences explain or develop the topic sentence
  3. Final sentence emphasizes the thought or states an important consequence

Avoid ending with a digression or unimportant detail.

Keep Related Words Together

The position of words in a sentence is the principal means of showing their relationship. Bring together the words and groups of words that are related in thought.

  • The subject and principal verb should not be separated by a phrase or clause that can be transferred to the beginning
  • Modifiers should come next to the word they modify

Express Co-ordinate Ideas in Similar Form

Parallel construction helps readers recognize likeness of content and function.

  • "Formerly, science was taught by the textbook method, while now the laboratory method is employed" → "Formerly, science was taught by the textbook method; now it is taught by the laboratory method"

Avoid a Succession of Loose Sentences

Don't construct whole paragraphs of two co-ordinate clauses joined by "and," "but," "so." Vary sentence structure with simple sentences, semicolons, and periodic sentences.

Keep to One Tense in Summaries

Choose present or past tense and stick with it throughout. Shifting tenses gives the appearance of uncertainty.

Grammar & Punctuation Essentials

  • Possessive singular: Add 's (Charles's friend, Burns's poems)
  • Series commas: Use comma after each term except the last (red, white, and blue)
  • Parenthetic expressions: Enclose between commas (The best way to see a country, unless you are pressed for time, is to travel on foot)
  • Co-ordinate clauses: Place comma before conjunction (The situation is perilous, but there is still one chance of escape)
  • Independent clauses: Don't join by comma alone; use semicolon or period
  • Sentence fragments: Don't break sentences in two with periods where commas belong
  • Participial phrases: At the beginning of a sentence, must refer to the grammatical subject

Common Usage Errors to Avoid

  • However: In the meaning "nevertheless," not to come first in its sentence
  • Less vs. Fewer: Use "less" for quantity, "fewer" for number
  • Like vs. As: "Like" governs nouns; before clauses use "as"
  • Very: Use sparingly. Where emphasis is necessary, use words strong in themselves
  • While: Don't use indiscriminately for "and," "but," or "although"

For AI Agents Specifically

When generating documentation, comments, or user-facing text:

  1. Prioritize clarity over cleverness
  2. Be direct - say what you mean in the fewest words
  3. Be specific - avoid vague abstractions
  4. Be active - prefer active voice unless passive is clearly better
  5. Be positive - tell the reader what IS, not just what ISN'T
  6. Be emphatic - put the most important information at the end

Remember: Your goal is to communicate clearly, not to impress with vocabulary or complexity.