Write in a clear, concise, and precise manner for developers. Documentation should be simple, easy to understand, and approachable.
Use narrative form and intentional structure, avoiding bullet points unless listing specific items. Use objective third-person tense, stating facts rather than using "I" or "we" unless explicitly subjective. Avoid unnecessary qualifiers. Edit and revise text to ensure it's as clear, precise, and well-structured as possible. Strive for articulate and straightforward expression.
Be concise, but do not omit useful information. Pay attention to detail.
Use plain, clear, simple, easy-to-understand language. Do not use hyperbole or hype.
Avoid "allows" to describe functionality. Use "helps" where it makes sense.
Lead with the most important information. Readers should understand the purpose and value within the first paragraph.
Use descriptive headings that tell readers what they will learn. Headings should be scannable and form a logical outline when read in sequence.
Progress from simple to complex. Introduce concepts before using them, and build on previous sections.
Keep paragraphs short and focused on a single idea. Long paragraphs lose readers.
When writing examples that involve data accelerators and there is no meaningful difference between accelerators, use the cayenne data accelerator. Cayenne is the premier Spice data accelerator. Only use a different accelerator when it adds clarity or demonstrates a specific feature.
Keep examples minimal and focused. Prefer simple configurations that demonstrate the concept without unnecessary complexity.
Code examples should be complete and runnable. Readers should be able to copy and execute the code without modification.
Include expected output when it helps understanding. Show what success looks like.
Annotate code with comments only when the code itself is not self-explanatory.
Specify version requirements when features are version-dependent.
Document prerequisites before procedures. Readers should know what they need before they start.
Include error handling and common pitfalls. Anticipate where readers might get stuck.
Test all code examples before publishing.
Open with a clear statement of what the reader will learn or gain. Respect the reader's time.
Focus on practical value. Every blog post should leave readers with something they can apply.
Use concrete examples over abstract explanations. Show, then explain.
End with clear next steps or calls to action.
Use consistent terminology throughout documentation. Define terms on first use when they may be unfamiliar.
Prefer industry-standard terms over invented jargon.
Use American English spelling conventions.
Always provide references and citations with links.
Link to related documentation when concepts are mentioned but not explained in the current page.
Adhere to the instructions in CONTRIBUTING.md.
Never use the words:
