Style Guide

General Writing Principles

• Keep language clear and concise.
• Prefer active voice (e.g., "Write the code" vs. "The code is written").
• Limit sentences to 20 words and paragraphs to 4 sentences.
• Use headings and subheadings for structure.
• Enhance explanations with examples or code snippets.

Documentation Style

Structure

• Follow a consistent layout: Introduction, Main Content, Conclusion.
• Use numbered steps for tutorials or procedures.
• Include prerequisites in a :::note admonition.

Formatting

• Use Markdown with Docusaurus syntax (e.g., front matter, tabs).
• Wrap code in blocks with language specified:

  ```bash npm install @volkovlabs/plugin ```

• Present data in tables for clarity:

  Option	Description
  timeout	Sets connection timeout (ms)

Language

• Explain technical terms for broader accessibility.
• Define acronyms on first use (e.g., "Grafana Query Language (GQL)").
• Maintain consistent terminology (e.g., "plugin" not "add-on").

Blog Post Style

Structure

• Start with an engaging intro to hook readers.
• Break content into sections with subheadings.
• End with a call to action (e.g., "Try it now").

Formatting

• Enhance with images or diagrams (stored in /static/img/).
• Use blockquotes for emphasis:

  Consistency is key to great content.

• Leverage Docusaurus tabs for options:
  • NPM
  • Yarn

  npm install @volkovlabs/plugin

Language

• Adopt a conversational tone to engage readers.
• Use storytelling to connect (e.g., "We faced this challenge...").
• Add personal insights where relevant.

Branding and Tone

• Embody Volkov Labs’ values: innovation, collaboration, excellence.
• Keep tone professional yet approachable.
• Use the Volkov Labs logo and colors (#9d70f9, #ffffff) consistently.

SEO Best Practices

• Weave keywords naturally into text.
• Add meta descriptions in front matter (e.g., description: "Guide to plugin setup").
• Use H1 (title), H2, and H3 tags logically.
• Link to internal docs and external resources.

Accessibility

• Ensure readability for all users (e.g., high-contrast text).
• Add alt text to images (e.g., ![Settings Panel](/img/settings.png "Plugin settings UI")).
• Provide transcripts for multimedia.
• Use descriptive link text (e.g., "Read the [guide](/docs/guide)")

Version Control and Updates

• Manage content with Git in a repository.
• Review and update quarterly, noting versions (e.g., "v2.1.0").