Documentation Guidelines

Overview

This guide covers the documentation structure and maintenance procedures for Rivusio.

Documentation Structure

docs/
├── index.md                 # Main landing page
├── getting-started/         # Getting started guides
├── user-guide/             # User documentation
├── maintainer/             # Maintainer documentation
├── api/                    # API documentation
└── examples/               # Code examples

Writing Documentation

Style Guidelines

1. Clear and Concise
2. Use active voice
3. Keep sentences short

4. Avoid jargon

5. Code Examples

6. Include type hints
7. Add comments for complex logic

8. Use realistic examples

9. Formatting

10. Use proper Markdown syntax
11. Include section headers
12. Add internal links

API Documentation

• Document all public APIs
• Include type information
• Provide usage examples
• Note deprecations

Building Documentation

# Install documentation dependencies
poetry install --with docs

# Build documentation
make docs

# Serve locally
make docs-serve

Updating Documentation

1. For New Features
2. Add API documentation
3. Update relevant guides

4. Include examples

5. For Changes

6. Update affected docs
7. Review related sections

8. Update version notes

9. For Deprecations

10. Mark as deprecated
11. Add migration guides
12. Update examples