Documentation guidelines and supports
tip
Document intentionality, concepts and metaphores.
Code documents itself, but you can't understand the aim that lead to a specific implentation, or how the code should evolve based only on what's written.
tip
Document for humans.
Be explicit on use cases that the project should cover and ilustrate with working examples.
Target audiences
- Develppers: Run, contribution, tests, implementation details
- Integration: api, sdk, events, error management, interface data models
- Data analysts: data semantics
- Target users: Use cases, features, metaphores, concepts
- Admins: setup, CI/CD, monitoring
Documentation order
- Valuie, Benefits
- project scope and responsabilities
- Concepts, metaphores
- Use cases, features
- sample scenarios
- Basic usage
- setup
- how to use
- Deployment
- deployment and ci
- monitoring metrics
- Integration
- api, sdk, jobs
- interface data models
- error management
- exposed data and meaning
- events semantics and triggers
- api, sdk, jobs
- Contributing
- Code conventions
- Project structure
- Documentation and tests guidelines
- Review process
- Specific algorithms in place