Documentation Guidelines¶

These guidelines define how documentation in the ReFlux project is written, structured, and maintained.
The goal is to keep documentation clear, consistent, scalable, and closely aligned with the codebase.

Purpose of Documentation¶

Documentation in ReFlux serves the following purposes:

Help engineers understand existing functionality quickly
Preserve architectural and business logic knowledge
Reduce onboarding time for new team members
Support operational troubleshooting and maintenance
Act as a reference during refactoring and feature expansion

Documentation is considered part of the product and should evolve together with the code.

What Should Be Documented¶

Documentation should be created or updated whenever one of the following happens:

A new backend app is created
A new large frontend module is introduced
A non-trivial feature or business flow is implemented
Architectural decisions are made
External integrations are added or changed
Operational procedures are defined or updated

If something is complex enough to require explanation during review, it should be documented.

Documentation Structure Principles¶

Follow these principles when creating documentation:

Organize by domain first (backend, frontend, operations)
For backend, document app by app
For frontend, document module by module
Keep files small and focused
Prefer multiple focused pages over one large page
Place documentation close to where it is referenced in navigation

Each folder should contain an index file explaining its purpose and linking to deeper documentation.

Backend Documentation Rules¶

For each backend app, documentation should include:

Purpose of the app
High-level responsibilities
Core concepts and domain language
Entry points such as APIs, tasks, or signals
Important data models and relationships
Non-obvious business rules
Operational or performance considerations
Known risks or pitfalls

When documenting individual files, focus on intent and behavior rather than repeating code.

Frontend Documentation Rules¶

Frontend documentation should be structured by module, not by technical layer.

For each module, document:

The user problem the module solves
Key pages or screens
Module boundaries and responsibilities
Data flow and state ownership
API interactions
Routing or navigation responsibilities
Reuse rules and dependencies
Testing expectations

Avoid documenting individual components unless they are complex or reused widely.

Writing Style Guidelines¶

When writing documentation:

Write for a future reader who has no context
Use simple and direct language
Prefer short paragraphs
Use headings to create clear structure
Use bullet lists for clarity
Explain why decisions were made, not just what was implemented

Assume the reader understands the technology stack but not the specific business logic.

Keeping Documentation Up to Date¶

Documentation must be updated when code changes.

Best practices:

Update documentation as part of the same change as the code
Treat outdated documentation as a defect
Do not leave placeholder sections permanently empty
Remove documentation for features that no longer exist

Incorrect documentation is worse than missing documentation.

Ownership and Responsibility¶

The author of a feature is responsible for its documentation
Reviewers should verify documentation during code review
Teams collectively own the quality of the documentation

Documentation quality is a shared responsibility.

When Not to Document¶

Avoid documenting:

Trivial or obvious code
One-line helpers
Self-explanatory configuration
Temporary experiments

Documentation should add value, not noise.

Documentation Review Checklist¶

Before considering documentation complete, confirm that:

Purpose is clearly explained
Scope and boundaries are defined
Important flows are understandable
Risks and edge cases are documented
Navigation links are logical
Language is clear and concise