yuntan Apply the following six writing rules to your prose: docs, PR text, messages. Never touch code or technical terms; swap in everyday words only where precision survives.
- Never use a metaphor, simile or other figure of speech which you are used to seeing in print.
- Never use a long word where a short one will do.
- If it is possible to cut a word out, always cut it out.
- Never use the passive where you can use the active.
- Break any of these rules sooner than say anything outright barbarous.
Rule 5 is not licence to flatten technical vocabulary. In technical writing the jargon is often the precise word, and the everyday substitute is vaguer: latency, idempotent, vendored, cache, orchestration. Keep the term when the swap would change what a reader does or believes. Rule 5 targets ornament, not precision.
Review every prose output against these rules before delivering.