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:
- Is the word needed at all? If the sentence means the same without it, delete it and stop.
- Is there a shorter word for this? If no, keep it and move on.
- 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.
- Does the swap break grammar or a fixed phrase? If yes, keep the long word.
- 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
usefour times beats reaching forutilizeon the third. Repetition is fine. Readers do not notice it. They noticeleverage. - 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.