Writing Contexts

Writing adapts to context while maintaining consistent voice. Each context has specific patterns, constraints, and examples.

User Interface

Buttons, labels, tooltips, errors, empty states, notifications

Constraints

Patterns

Button

Formula: Action verb + object

• Start with a verb
• Be specific about the action
• Avoid 'Submit' except for forms

Examples:

• "Save changes"
• "Start audit"

Error

Formula: What happened + How to fix

• Be specific about the problem
• Provide actionable next steps
• Don't blame the user
• Avoid technical jargon

Examples:

• "Couldn't save. Check your connection and try again."
• "Invalid email format. Please enter a valid email address."

Empty State

Formula: What goes here + How to add it

• Explain what the area is for
• Provide clear next action
• Be encouraging, not critical

Examples:

• "No audits yet. Create your first audit to get started."
• "Your inbox is empty. New messages will appear here."

Confirmation

Formula: Action + Consequences (if destructive)

• State the action clearly
• Warn about permanent consequences
• Make cancel easy and clear

Examples:

• "Delete this audit? This action cannot be undone."
• "Remove team member? They will lose access immediately."

Tooltip

Formula: Brief explanation + Context if needed

• Keep under 100 characters
• Explain non-obvious features
• Avoid repeating the label

Notification

Formula: What happened + Next step (if any)

• Be timely and relevant
• Provide context for action
• Allow dismissal

Marketing Copy

Website, landing pages, ads, social media, emails

Guidelines

• Lead with benefit, not feature
• Use specific numbers over vague claims
• Address the reader as 'you'
• Create interest without overhyping
• Back claims with evidence

Patterns

Headline

Formula: Benefit statement

Examples:

• "AI that understands your customers"
• "Audit 10x more interactions without more staff"

Subhead

Formula: Expand headline with specifics

Cta

Formula: Action verb + Value

Examples:

• "See how it works"
• "Get started free"

Value Prop

Formula: What you get + How it helps

Don't:

• Superlatives without evidence (best, fastest, revolutionary)
• Aggressive urgency (Act now! Limited time!)
• Empty buzzwords (synergy, leverage, paradigm shift)
• Vague claims (world-class, cutting-edge)

Technical Documentation

API docs, guides, tutorials, READMEs, specifications

Guidelines

• Write procedures as numbered steps
• One action per step
• Include expected outcome
• Define acronyms on first use
• Use second person ('you')
• Include code examples

Patterns

Procedure

Formula: Numbered steps with single actions

• Start each step with a verb
• Include expected result
• Note potential issues

Concept

Formula: Definition + Context + Example

• Define the term first
• Explain why it matters
• Provide concrete example

Reference

Formula: Parameter + Type + Description + Default

• List all parameters
• Note required vs optional
• Include valid values

Code Example

• Include what it does
• Show expected output
• Note prerequisites

Legal Documents

Terms of service, privacy policy, contracts, compliance docs

Guidelines

• Use plain language where legally possible
• Define all technical and legal terms
• Use 'shall' and 'must' for obligations
• Use 'may' for permissions
• Be precise about parties and obligations
• Structure for clarity with headings

Patterns

Definition

Formula: 'Term' means definition.

Obligation

Formula: Party must/shall action.

Permission

Formula: Party may action.

Prohibition

Formula: Party must not / shall not action.

Don't:

• Unnecessarily complex language
• Ambiguous terms
• Hidden important information
• Inconsistent terminology

Customer Support

Help articles, support tickets, chat responses, FAQs

Guidelines

• Acknowledge the user's situation
• Be solution-oriented
• Show empathy without being patronizing
• Provide clear next steps
• Follow up proactively

Patterns

Acknowledgment

Examples:

• "I understand this is frustrating."
• "Thanks for reaching out about this."
• "I can see why that would be confusing."

Solution

Formula: What to do + Why it works

Escalation

Formula: What's happening + What you'll do

Don't:

• Dismissing concerns
• Robotic template responses
• Blaming the user or other systems
• Making promises you can't keep

Email Communications

Transactional, marketing, support, internal emails

Patterns

Subject

• Be specific and clear
• Front-load important words
• Avoid spam triggers

Examples:

• "Your weekly audit report"
• "Action required: Verify your email"

Body

• Lead with the most important information
• One main topic per email
• Clear call-to-action
• Scannable structure

Commercial Documents

Proposals, contracts, quotes, invoices, business correspondence

Guidelines

• Balance professionalism with approachability
• Be clear about deliverables and terms
• Use structured formatting
• Highlight value, not just features
• Make next steps clear

Patterns

Proposal

Quote

Don't:

• Overly aggressive sales language
• Hidden terms or conditions
• Vague scope or deliverables
• Jargon without explanation