Style guide

Style Guide

Documentation Style Guide

This style guide is designed to ensure consistency and clarity across all Octopipe documentation. Whether you’re writing code documentation, tutorials, or API references, please follow these guidelines to maintain a high standard of quality.

Tone and Voice

• Friendly and Professional: Use a conversational tone that is both approachable and professional.
• Clear and Concise: Aim for clarity and brevity. Avoid unnecessary jargon and overly complex sentences.
• Inclusive: Write in a way that is accessible to all users, regardless of their technical background.

Formatting Guidelines

• Headings: Use Markdown heading levels (#, ##, ###, etc.) to structure content logically.
• Lists and Bullet Points: Use bullet points or numbered lists to break down complex information.
• Code Blocks: Use triple backticks () for code blocks. Provide language hints (e.g., bash, ```python) where applicable.
• Inline Code: Wrap inline code in backticks (code) to distinguish it from regular text.
• Links: Use descriptive link text instead of raw URLs for better readability.

Writing Guidelines

• Active Voice: Write in the active voice to make instructions clear and direct.
• Consistent Terminology: Use consistent terms for commands, options, and technical concepts throughout the documentation.
• Examples: Include real-world examples and sample commands to help users understand the context.
• Formatting Emphasis: Use bold for important terms and italics for emphasis when needed.

Documentation Structure

• Introduction: Begin with a brief overview of the topic.
• Step-by-Step Instructions: Break down tasks into clear, numbered steps.
• Additional Resources: Provide links to related documentation or external resources.
• Troubleshooting: Include a section for common issues and solutions when applicable.

Visual Elements

• Screenshots and Diagrams: Use images to supplement complex instructions. Ensure all visuals have descriptive alt text.
• Tables and Lists: Use tables for structured data and lists to outline features or steps clearly.

Reviewing and Editing

• Proofreading: Check for spelling and grammar errors before submitting changes.
• Consistency: Review documentation to ensure consistent use of terms and formatting.
• Peer Review: Encourage others to review your contributions to catch errors and improve clarity.

Updating the Style Guide

This style guide is a living document. As Octopipe evolves, the guide may be updated. Contributors are encouraged to suggest improvements or clarifications.

Conclusion

By adhering to this style guide, you help create documentation that is clear, consistent, and easy to use. Thank you for your commitment to quality and for helping to make Octopipe’s documentation a valuable resource for the community!