Craft
Writing Style
We write in ventilated prose. Short sentences. Clear language. One idea per line.
Style
How We Write
- Keep sentences short and meaningful.
- Use line breaks generously. One idea per line.
- Put links on their own lines when possible.
- Write in clear, simple language. No jargon for the sake of jargon.
This style makes editing easier. You can insert a new line without rewriting a whole paragraph.
Voice
Our Voice
Use "we" instead of "you" when explaining concepts.
Example
No: By default, Rails assumes that the attribute name is token. You can provide a different name as a parameter.
Yes: By default, Rails assumes that the attribute name is token. We can provide a different name as a parameter.
Do not use placeholder examples like foo, bar,
or baz. Use realistic examples that reflect actual use cases.
Every blog starts with an introduction: what problem are we solving, why it matters, and what the reader needs to know first. Never start with code.
Structure
Before and After
When writing about a new framework feature, always include a "before" section. Show how things worked previously, then show the improvement.
- Before: Explain the limitation or workaround.
- After: Show how the new feature solves it.
This gives context. A reader who does not know the old way will not appreciate the new way.