Writing style
Clear, direct, quantitative prose that respects the reader's time and intelligence.
Voice and tone
Active voice
Put the actor first. Active voice is direct, clear, and assigns responsibility. Passive voice obscures who did what and adds unnecessary words.
"PolicyEngine calculates marginal tax rates for 50 million households."
"Marginal tax rates are calculated by PolicyEngine for 50 million households."
Direct and concise
Say what you mean without hedging. Cut filler words. Every sentence should advance the reader's understanding.
"The reform raises $50 billion annually."
"It is worth noting that the reform would potentially be expected to raise approximately $50 billion on an annual basis."
Quantitative precision
Numbers over adjectives
Replace vague modifiers with specific quantities. "Large," "significant," and "substantial" tell readers nothing. Numbers tell them everything.
"The policy reduces child poverty by 34%, lifting 2.1 million children above the poverty line."
"The policy significantly reduces child poverty, helping many children."
Precise comparisons
When comparing, use percentages, ratios, or absolute differences. Specify the baseline and timeframe.
"Benefits increase 23% relative to 2024 levels, from $3,600 to $4,428 per child."
"Benefits increase substantially compared to before."
Uncertainty when warranted
When precision isn't possible, be explicit about uncertainty. Ranges and confidence intervals are more honest than false precision.
"The revenue estimate ranges from $40B to $60B, depending on behavioral response assumptions."
"The revenue estimate is $50B." (when uncertain)
Corroboration of claims
Falsifiable claims require sources
Every factual claim that could be wrong must be corroborated. Link to primary sources, academic papers, or official data. If a claim can't be verified, either find a source or remove the claim.
- Statistics: Link to the dataset or publication
- Policy details: Link to legislation or official guidance
- Research findings: Link to the paper (preferably DOI)
- Historical facts: Link to reliable sources
Primary over secondary sources
Prefer original sources over summaries. Link to the CBO report, not the news article about the CBO report. Link to the legislation, not the think tank summary.
Acknowledge limitations
State what the evidence does and doesn't show. Note methodological limitations. Don't overclaim based on preliminary or contested findings.
Structure and flow
Flowing narrative over bullets
Prefer connected prose that guides readers through an argument. Bullets fragment ideas and lose the logical connective tissue. Use bullets only for genuine lists (features, requirements, steps).
"The reform works in three stages. First, it expands eligibility to households earning up to 400% of the poverty line, adding 12 million families. Second, it increases benefit amounts by indexing them to median wage growth rather than inflation. Third, it simplifies claiming by integrating with existing tax filing."
"Key changes:
• Expanded eligibility
• Increased benefits
• Simplified claiming"
Vary sentence length
Mix long explanatory sentences with short punchy ones. Monotonous sentence length—whether all long or all short—tires readers. Short sentences after complex ones provide breathing room.
Front-load key information
Lead with the conclusion or main point. Readers should understand the takeaway from the first paragraph, then get supporting detail. Don't bury the lede.
Formatting conventions
Sentence case for headings
Capitalize only the first word and proper nouns. This follows the modern standard used by Apple, Google, Slack, and GOV.UK.
"What PolicyEngine does"
"What PolicyEngine Does"
Numbers in text
Spell out zero through nine; use numerals for 10 and above. Always use numerals with units (5%, $3M, 7 million households). Use numerals in data-heavy contexts for consistency.
Links
Use descriptive link text that indicates the destination. Avoid "click here" or bare URLs. Link text should make sense out of context.
"See the CBO's 2024 budget outlook for projections."
"For projections, click here."