Skip to main content

Style Guide

This style guide provides best practices for crafting clear, consistent, and engaging documentation and blog posts for Volkov Labs. Following these guidelines ensures content reflects our brand values and resonates with our audience—developers, admins, and users.

Last Updated: April 10, 2025

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 :::info 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:
    OptionDescription
    timeoutSets 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.

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").