simonrw Improve Writing
A path to higher quality written output.
Guidance
- Formal, neutral and professional language: Avoid colorful or figurative language. We are writing docs that are intended to be dry and concise. There is no need to make them exciting. Avoid colloquialisms.
- Avoid dashes and (semi)colons Use direct and active language that avoids the need for dashes or (semi) colons. Avoid paratactic style, asyndetic construction, parenthetical construction and appositive construction.
- Colons after list elements If a list item has emphasised 'header' word(s) use a colon afterwards not a period. Take this list as an example.
- Avoid bullet pointed lists: Only use bullet pointed lists when they actually make sense and you are enumerating elements of a set. Do not use them as a general mechanism to structure text that can also be structured as paragraphs.
- Use emphasis intentionally: Use emphasis (bold, italic) to guide the reader through the doc. Emphasised text provides the reader with anchors when quickly glancing over a page. They serve an important role in navigation and overview.
- Plain words first: Use simple words and language unless a specific technical term is more precise and that precision is actually meaningful in the context. E.g. use Send instead of dispatch unless dispatch carries information the simpler verb does not.
- No decoration: Omit decorative language that does not add relevant meaning. Examples for this are words like orchestration, pipeline, synergy, first-class, platform-grade, etc...
- Use technical vocabulary precisely, not as flair: Contract, boundary, observer, layer, primitive, interface each carry a specific engineering meaning. Use them only when you mean exactly that. If a plainer word fits, prefer the plainer word.
- No techno babble: Avoid any cool sounding words just for the purpose of adding color. If a specific term carries meaning that can not be expressed otherwise/in a simple way, use it, but omit otherwise.
- Stable terms: Once a doc has introduced a name for a thing, do not switch to a synonym later. Either use the defined term or the plainest possible alternative — never a third invented synonym in the same doc.
- Active voice, entity-first: The subscription emits an event when its plan changes beats An event is emitted by the system upon subscription plan change events. Lead with the thing that acts.
- No hedging in factual statements: Might, could, generally, typically — if something is uncertain, it belongs in Open Questions or marked as such. If it is fact, state it directly.
- Sections only where appropriate: Use sections
---only when areas of text are disjoint. Do not use them as a structuring mechanism where simple headers could be used instead. - Precision: Precision is of utmost importance. If a concrete name is used, expecially when using it with code decoration (
examble) then this name must exactly match the source code. Simplifications are not allowed, becuase if the name changes then it does not identify that concrete element anymore.