Documentation

This guide provides practical information about writing and maintaining documentation for the Cloacina project.

Documentation Structure

Our documentation follows the Diátaxis Framework and is organized into:

docs/content/tutorials/ - Step-by-step guides and examples that teach Cloacina features
docs/content/how-to/ - Task-oriented guides for specific operations
docs/content/reference/ - Technical reference and API documentation
docs/content/explanation/ - Conceptual documentation and deep dives

Writing Guidelines

General Principles

Write clear, concise, and accurate documentation
Use active voice and present tense
Include practical examples where appropriate
Keep documentation up-to-date with code changes
Consider the reader’s perspective and experience level

API Documentation and Cross-Linking

When documenting API features or referring to API components in the documentation, use the api-link shortcode. It uses Rust’s namespace syntax to create links:

{{< api-link path="path::to::component" >}} Renders as: cloacina::models

You can also customize the display text: {{< api-link path="path::to::component" display="Custom Text" >}} Example: Data Models

Item Types

The shortcode supports different Rust item types through the optional type parameter:


    cloacina::context::Context
    



    <!-- For structs -->

    cloacina::task::Task
    



           <!-- For traits -->

    cloacina::models
    



              <!-- For modules -->

    cloacina::error::Error
    



          <!-- For enums -->

    cloacina::types::Result
    



         <!-- For type aliases -->

    cloacina::utils::format_error
    



     <!-- For functions -->

Available types:

struct - For structs (default if not specified)
enum - For enums
trait - For traits
type - For type aliases
fn - For functions
module - For modules (uses index.html)

These links will automatically stay up-to-date with the API documentation.

Documentation Review Process

Self-Review
- Check for technical accuracy
- Verify all links work
- Ensure examples are up-to-date
- Review for clarity and completeness
Peer Review
- Documentation changes should be reviewed by at least one other contributor
- Focus on both technical accuracy and clarity
- Consider the perspective of new users

Tools and Resources

Use the Hugo development server to preview documentation changes:
```
hugo server -D
```
Check the Hugo documentation for markdown syntax and shortcodes
Review existing documentation for style and format consistency

Need Help?

If you need assistance with documentation:

Check existing documentation for examples
Ask in the project’s communication channels
Review the Diátaxis Framework for guidance on documentation types