Skip to content
- Contributing to docs should be easy. We value our teammates’ ability to contribute great documentation. Keep this “meta-documentation” up to date.
- Focus on user needs. We value empathy for our teammates and users. Put yourself in the user’s shoes when planning and writing. Write from the perspective of what the user needs to do, rather than what the technology can do.
- Documentation is part of the work. We value our users’ experience with an evolving system. Every code or system change must be accompanied by timely additions, changes, or removals to the relevant documentation.
- Default to open. We value open source and on premise customers. Document in public unless there’s a clear reason not to (e.g., internal environment details).
- Kessel operations are first-class. We value operable systems that both us and our users can feel comfortable running. Keep internal docs for internal details only.
- Use proven models. We stand on the shoulders of giants. Follow Diátaxis (used by Django, Cloudflare, etc). Know whether you’re writing a tutorial, how-to, explanation, or reference, and write with that user need in mind.
- Aim for minimal, coherent, and up to date. We value pragmatism and maintainability. Placeholder content is okay. Prioritize clarity over completeness. Every sentence is another to maintain. Better to ship something small and usable than bloated, unmaintainable, or out of date.
- Comment the API spec. We value usable interfaces. If your change affects API behavior, schema, or operations, ensure the proto is commented.
- Think like a product owner. We value quality. When adding docs, place them intentionally. Consider where they belong and how they relate to what’s already written. Title them consistently. Use correct grammar.