Writing standards
This page outlines the writing standards we follow at Lerian to keep our documentation clear, consistent, and easy to use. Whether you're writing a new guide or updating an existing API reference, follow these practices to ensure your content feels cohesive and helpful.
Voice and tone
At Lerian, we write the way we work: with confidence, clarity, and care. Our tone is:
- Assertive, but never arrogant – we say what needs to be said, clearly and without overexplaining.
- Encouraging and empowering – we guide users to make progress, especially when things get complex.
- Tech-savvy, but human – we talk to developers, not at them. We use technical terms when needed, but we always aim for clarity over jargon.
- Humble and open – we’re confident in our solutions but always assume there’s more to learn.
TipWhen in doubt, write like you’re helping a smart colleague who just joined the team.
Writing standards
We follow the Google Developer Documentation Style Guide as our baseline. Some key principles include:
- Use active voice whenever possible: “This plugin handles authentication,” not “Authentication is handled by this plugin.”
- Keep sentences short and clear. Aim for one idea per sentence.
- Use present tense for general truths and functionality: “The service validates the request.”
- Avoid unnecessary words: Prefer “use” over “utilize,” “start” over “commence,” “if” over “in the event that.”
TipFor deeper guidance, refer directly to the style guide.
Capitalization
We use sentence case for all headings and titles. That means only the first letter of the sentence and proper nouns are capitalized.
✅ Correct | ❌ Avoid |
---|---|
Getting started with the API | Getting Started With The API |
Using the transaction builder | Using The Transaction Builder |
This applies to:
- Page titles
- Section headings
- Card titles
- Navigation labels
Updated 9 days ago