Research about software documentation and how integrate in the project

# Research Summary

After reviewing the **Docs as Code** approach and different alternatives for software documentation, I think RobinHoot should manage its documentation following the same workflow as the source code.

## Docs as Code

The documentation should:

- Live inside the same repository as the source code.
- Be versioned with Git.
- Be updated through feature branches and Pull Requests.
- Be reviewed together with the implementation.
- Evolve together with the software.

This approach keeps documentation synchronized with the implementation, reduces outdated documentation, and encourages collaboration between developers.

---

# UML Documentation

Based on the reviewed alternatives, Mermaid.js appears to be a good fit for RobinHoot because:

- Diagrams are stored as plain text.
- They can be embedded directly into Markdown files.
- GitHub renders Mermaid diagrams natively.
- Changes are visible in Git diffs and Pull Requests.
- There is no need to maintain binary diagram files.

Example:

```mermaid
sequenceDiagram
User->>API: Login
API->>Database: Validate credentials
Database-->>API: Success
API-->>User: JWT
```

## Other alternatives reviewed

The following alternatives were considered:

- Mermaid.js
- PlantUML
- Draw.io
- Structurizr DSL

For RobinHoot, Mermaid.js provides the best balance between:

- Simplicity
- Maintainability
- GitHub integration
- Docs as Code compatibility

## SDD Integration

The issue raises an important question:

> Should UML documentation be managed separately from the Software Design Document (SDD)?

**My recommendation is no.**

Instead of maintaining UML diagrams in a separate location, they should be embedded directly into the corresponding Markdown documents that make up the Software Design Document.

For example:

```
docs/
├── README.md # Documentation overview
│
├── requirements/ # What the system should do
│ ├── user-stories.md
│ ├── business-rules.md
│ └── glossary.md
│
├── specs/ # OpenSpec specifications
│ ├── authentication.md
│ ├── users.md
│ └── projects.md
│
├── architecture/ # SDD (Markdown + Mermaid)
│ ├── overview.md
│ ├── context.md
│ ├── components.md
│ ├── deployment.md
│ ├── authentication.md
│ └── users.md
│
├── adr/ # Architecture Decision Records
│ └── ADR-0001.md
│
└── contributing.md # Documentation guidelines
```

Each document should contain both the architectural explanation and the Mermaid diagrams describing that part of the system.

This avoids duplicated documentation and keeps diagrams synchronized with the architecture.

## Documentation Structure

### `README.md`

Entry point for the documentation.

It should explain:

- Documentation strategy.
- Folder organization.
- Documentation workflow.
- Contribution guidelines.

### `requirements/`

Contains the business requirements of the project.

Typical contents include:

- User Stories
- Business Rules
- Functional Requirements
- Shared terminology (Glossary)

This documentation answers the question:

> **What does the business need?**

### `specs/`

Contains the functional specifications following the OpenSpec approach.

Each specification should describe:

- Expected behavior
- Acceptance criteria
- Business rules
- Error scenarios
- Preconditions and postconditions

This documentation answers:

> **How should the system behave?**

### `architecture/`

Contains the Software Design Documentation (SDD).

Examples:

- Architecture Overview
- Context Diagram
- Component Diagram
- Class Diagram
- Sequence Diagram
- Deployment Diagram

All UML diagrams should be written using Mermaid.js inside Markdown files.

### `adr/`

Each ADR documents an important architectural decision, including:

- Context
- Decision
- Consequences

Examples:

- Why Mermaid.js was selected.
- Why DDD was adopted.
- Why a specific technology was chosen.

This documentation answers:

> **Why was this decision made?**

### `contributing.md`

Defines the documentation contribution process.

Examples:

- Documentation standards.
- Markdown conventions.
- Mermaid diagram guidelines.
- When documentation should be updated.
- Documentation review process.

This documentation answers:

> **How should contributors maintain the documentation?**

---

# Future Improvements

Since RobinHoot plans to adopt Domain-Driven Design (DDD), OpenSpec (Specification Driven Development), and User Stories, the documentation can later evolve to include these artifacts as part of the documentation strategy.

A possible documentation workflow could be:

```
User Story
↓
OpenSpec Specification
↓
Domain Model (DDD)
↓
+----------------------------------------------------+
| Software Design Document (SDD) |
|----------------------------------------------------|
| • Architecture |
| • Design Decisions |
| • Mermaid UML Diagrams |
+----------------------------------------------------+
↓
Implementation (TDD)
```

With this approach, UML diagrams become a representation of the design instead of the starting point, keeping every architectural decision traceable back to business requirements and specifications.

---

# Conclusion

Rather than treating UML documentation as an isolated activity, RobinHoot should adopt a unified documentation strategy based on Docs as Code.

Documentation should evolve together with the source code, using Git, Pull Requests, and Markdown as the primary workflow. The Software Design Document (SDD) should integrate Mermaid diagrams directly within its Markdown files, keeping architecture documentation consistent, versioned, and easy to maintain.

As the project evolves with Domain-Driven Design (DDD), OpenSpec, and User Stories, the documentation structure can naturally grow while remaining aligned with the same Docs as Code philosophy.