Blogs
Writing Style
We prefer a clear, ventilated prose style that makes technical articles easier to follow and easier to revise over time.
Style
Writing Style
We prefer writing blogs using a ventilated prose style.
Key principles:
- Keep sentences short and meaningful
- Avoid long or complex sentences
- Write in clear and simple language
- Use line breaks generously
- Put links on separate lines where appropriate
- Write one idea per line
Examples
Line breaks are especially useful:
- After links
- After code blocks
- After section headings
Keeping ideas separated makes editing easier later, because new lines can be inserted without rewriting a whole paragraph.
Content
Content Guidelines
Writing Voice
Use "we" instead of "you" when explaining concepts.
Example
Incorrect
By default, Rails assumes that the attribute name is token. You can provide a different name as a parameter.
Correct
By default, Rails assumes that the attribute name is token. We can provide a different name as a parameter.
This style keeps the tone collaborative and consistent with our company voice.
Avoid Placeholder Examples
Do not use placeholder examples such as foo, bar, or baz.
Instead, use realistic examples that reflect actual use cases.
Always Start with an Introduction
Every blog must begin with a short introduction explaining:
- The problem being solved
- Why the topic matters
- Background context
- Any prerequisites
Avoid starting directly with code or technical details.
Example introduction topics:
- A problem faced by a client
- A limitation in an existing framework
- A feature introduced in a new version
Use a "Before" Section for New Features
If the blog explains a new framework feature, include a section explaining how things worked before.
- Before: Explain limitations or workarounds required previously.
- After: Explain how the new feature solves the problem.