Writing rules

Reference: Short words

The rule as we use it, word for word. Every piece on the site is edited against it.

Binding for every piece of prose written in this workspace: docs, skills, READMEs, served pages, screen text, reports and generated output. Read it in full before writing or editing any of them.


The rule

First ask whether the word is needed at all; if not, delete it. When a shorter word does the same job, use the shorter word. Count syllables, not letters. Fewer syllables wins.

If swapping the long word for the short one costs nothing in meaning, make the swap. Every time.


How to apply it

For each content word, run this test in order:

  1. Is the word needed at all? If the sentence means the same without it, delete it and stop.
  2. Is there a shorter word for this? If no, keep it and move on.
  3. Does the swap change what the sentence means? If yes, keep the long word. Name the difference to yourself. If you cannot name it, there is no difference.
  4. Does the swap break grammar or a fixed phrase? If yes, keep the long word.
  5. Otherwise: swap.

Syllables are the metric. get rid of (3 syllables, 3 words) beats eliminate (4 syllables, 1 word). Word count is not the target. Density of sound is.


Valid reasons to keep the longer word

These are the only ones.

The long word is narrower. Purchase and buy differ in a contract. Terminate and stop differ in employment law. Deduce and figure out differ in a proof. When the long word carries a meaning the short one does not, keep it.

It is a term of art. Deploy in software, execute in law, acquire in finance, validate in data. Fixed technical vocabulary is a noun in disguise. Do not translate it. Here that includes every identifier, column and table name, and the categorising and grading vocabularies (identical / cosmetic / structural, PASS / WARN / FAIL, Confirmed / Possible).

It is part of a fixed phrase. Perform surgery, not do surgery. Conduct an investigation, not do an investigation. English collocation is arbitrary and you have to respect it.

It is a proper name or quoted text. This includes a UI string quoted as the screen shows it.

The short word is ambiguous in context. Run has forty meanings. If operate removes a genuine misread, use operate.


Not valid reasons

Reject all of these.

  • Flair. Not a reason.
  • Rhythm, cadence, flow, music. Not a reason.
  • Variety. Repeating use four times beats reaching for utilize on the third. Repetition is fine. Readers do not notice it. They notice leverage.
  • Sounds more professional. The long word does not sound smarter. It sounds like padding.
  • Sounds more precise. If it were more precise you could name the difference. See exception 1.
  • The audience is technical. Technical readers skim harder than anyone.
  • The tone is formal. Formal register comes from structure and word choice across the whole piece, not from Latin roots on every verb.

Substitutions

Use the left column. Reach for the right column only under a valid exception.

Verbs

Use Instead of
use utilize, leverage, employ
help facilitate, assist, enable
make create, generate, produce, craft
get obtain, acquire, secure, procure
give provide, offer, deliver, furnish
put place, position, situate
keep maintain, retain, preserve, sustain
let allow, permit
show demonstrate, illustrate, showcase
tell inform, convey, communicate
ask inquire, request, solicit
do perform, execute, conduct
try attempt, endeavor, seek to
find identify, locate, uncover
fix resolve, remediate, rectify
check verify, validate, assess
change modify, alter, adjust
cut reduce, minimize, streamline, curtail
add incorporate, integrate, augment
build construct, develop, architect
pick select, opt for
send transmit, dispatch, forward
think consider, contemplate
want desire, wish, seek
need require, necessitate
buy purchase, procure
talk discuss, converse, engage with
run operate, administer
move transition, migrate, shift
start initiate, commence, embark on
stop cease, terminate, discontinue
teach educate, instruct
lead spearhead, orchestrate
see observe, perceive
grow increase, escalate, expand
drop decrease, decline, diminish

Phrasal verbs

The largest and most reliable gain. Two small words almost always beat one long one.

Use Instead of
find out determine, ascertain
figure out deduce, derive
come up with devise, formulate
get rid of eliminate, discard
set up establish, configure, institute
deal with address, handle, manage
look into investigate, examine, explore
go over review, examine
point out highlight, indicate
bring up raise, introduce
back up substantiate, corroborate
work out resolve, calculate
turn into transform into, convert to
put off postpone, defer
rule out exclude, preclude
leave out omit, exclude
lay out outline, delineate
take on assume, undertake
give up abandon, relinquish, forgo
run into encounter, experience
sort out resolve, rectify
keep up maintain, sustain
pull off accomplish
cut down reduce, decrease
hold off defer, refrain from

Nouns

Use Instead of
thing element, aspect, factor
stuff materials, content, resources
way method, approach, methodology, mechanism
idea concept, notion, framework
job role, function, position
goal objective, aim, target
plan strategy, roadmap, initiative
part component, facet, segment, dimension
rule guideline, policy, principle
chance opportunity, likelihood, probability
gap discrepancy, shortfall, deficiency
risk exposure, vulnerability
flaw limitation, shortcoming, drawback
size magnitude, scale
speed velocity, pace
cost expenditure
staff personnel, resources
boss supervisor, leadership
drop decline, reduction
rise increase, uptick
proof evidence, validation
time duration, timeframe, period
place location, venue, setting
test assessment, evaluation
tool instrument, mechanism, solution
step phase, stage, procedure
help assistance, support, guidance

Adjectives

Use Instead of
big significant, substantial, considerable, major
small minimal, modest, limited, negligible
good effective, beneficial, optimal, favorable, robust
bad suboptimal, problematic, detrimental, adverse
new novel, emerging, innovative, cutting-edge
old legacy, established, longstanding
hard challenging, complex, demanding
easy straightforward, seamless, accessible
fast rapid, expedient, accelerated
slow gradual, protracted
clear evident, apparent, transparent
vague ambiguous, nebulous, opaque
same identical, equivalent, uniform
main primary, principal, core, central, key
whole entire, comprehensive, holistic
deep profound, substantive, in-depth
strong robust, powerful
weak insufficient, inadequate
right correct, accurate, appropriate
wrong incorrect, erroneous
enough sufficient, adequate
cheap cost-effective, economical, affordable

Connectives and adverbs

The loudest tell. Highest priority to fix.

Use Instead of
so therefore, consequently, accordingly, thus
but however, nevertheless, nonetheless
also additionally, furthermore, moreover
because due to, owing to, as a result of, given that
to in order to, with a view to
about regarding, concerning, with respect to
by via, by means of
if should, in the event that, provided that
like akin to, comparable to
now currently, presently, at this juncture
later subsequently, thereafter
before prior to, previously
then subsequently, at that point
first initially
last ultimately, finally, in conclusion
a lot significantly, considerably, substantially
a bit somewhat, slightly, marginally
maybe perhaps, potentially, conceivably
often frequently, commonly, regularly
almost nearly, virtually
most the majority of, predominantly

Traps

Longer phrase, fewer syllables. In order to is 4 syllables across 3 words. To is 1. Take it. Never count words.

Fake swaps. Make use of is not shorter than use. Go to the root verb, not a padded version of it.

Nominalization. Long nouns hide long verbs. Provide an explanation of becomes explain. Conduct an analysis of becomes analyze and then look at. Unpack the noun first, then shorten the verb.

Chained swaps. One swap often unlocks another. Utilize this in order to facilitate the identification of issues becomes use this to help find bugs. Run the pass twice.

Downshifting everything. Uniform short words is its own flat texture. The aim is that no long word survives without a reason, not that no long word survives. When an exception is valid, the long word stays and the contrast does work for you.


Self-check

Before you ship a draft, scan for these. Each one is a near-certain fix.

utilize · leverage · facilitate · in order to · furthermore · moreover · additionally · subsequently · therefore · thus · nevertheless · with respect to · prior to · a significant number of · it is important to note that · demonstrate · implement · robust · seamless · comprehensive · ascertain · endeavor

If the draft still reads long, the problem has moved from words to sentences. See the least-first reference.


Tooling

The list can be enforced by tooling. Where a project has the checker, python3 scripts/check_short_words.py scans every project .md and exits 1 on a hit. It parses its terms from the Self-check list above and the one in least-first, so those lists are what it checks. It also fails on any [NEED] mark left from writing-stages. A word kept under a valid exception stays: wrap it in backticks, or add a <file>::<word> line to scripts/short-words-allow.txt, which is where the reason for keeping it gets written down.

--full widens the scan to every long word in the Substitutions tables above, printing the short form beside each hit, and to the filler words in writing-mechanics. --seams prints the first and last sentence of each paragraph, for the least-first seam check. That pass is advisory, not a gate: the tables read in one direction only, so handle, materials, secure, review and content all fire on ordinary domain vocabulary, and a few listed swaps (slightly -> a bit, encounter -> run into) cost the same syllables they save. Read it as a worklist, not a verdict.

Back to how we use AI