Skip to content

Documentation Style Guide

This document outlines the style guide for writing and editing documentation for the Loki project. Please follow these guidelines when contributing to our documentation.

General Guidelines

  • Use clear and concise language.
  • Write in the second person (you, your) to address the reader.
  • Use American English spelling and grammar.
  • Use Markdown syntax for formatting.
  • Use code blocks for code snippets, using the appropriate language identifier.
  • Use headings (#, ##, ###, etc.) to structure the document.

Documentation Structure

Each documentation page should have the following structure:

  1. Title (#)
  2. Introduction (optional)
  3. Table of Contents (optional)
  4. Main Content
  5. Conclusion (optional)
  6. References (optional)

Code Examples

  • Use code blocks for code examples.
  • Use the appropriate language identifier for code blocks.
  • Explain the purpose and usage of the code example.
  • Use comments in code examples to explain complex or non-obvious parts.
  • Use inline links for external resources.
  • Use relative links for internal resources.
  • Provide a descriptive link text.

Images

  • Use images sparingly, only when they add value to the documentation.
  • Use the appropriate image format (PNG, JPEG, SVG, etc.).
  • Provide a descriptive alt text for images.

Versioning

  • Documentation should be versioned along with the codebase.
  • Use the appropriate version tag in the documentation file name or URL.

Review Process

  • All documentation changes should be reviewed by at least one other contributor before merging.
  • Use GitHub pull requests to submit and review documentation changes.

Please follow these guidelines when contributing to our documentation. If you have any questions or suggestions, please open an issue on our GitHub repository.