Hasura Docs Wiki
Welcome to the Hasura Docs Wiki! We're glad you're here and are excited to see your docs contributions. They're going to be great π
On the following pages, you'll find all the information you need to get started. A perfect place to begin would be the Contributing to Docs page that will walk you through the end-to-end contribution process from setting up your local development environment to creating your first PR.
Get started with documentationβ
What is good documentation?β
Good documentation uses clear, simple, effective communication to explain the usage and workings of our product as completely as possible.
Documentation is critically important. It's our most visited web property besides the homepage and without good, thorough documentation, users can not use, or enjoy using our product.
If a product feature doesnβt have excellent feature and reference documentation then it is not a finished feature.
Good documentation is vital to the health of our company and brand. Users often discover new features or upgrade based on information they find in documentation.
Every Hasurian is responsible for creating and continually improving the documentation.
Your task is to create rich, correct documentation content which fully covers the feature being referenced in a user-obsessed, complete and compelling way.
Types of documentationβ
We strive to create quality, rich content in four logical areas of documentation including:
- Explanation
- Task guides
- Tutorials
- Reference
It is your task to consider which of these types of documentation fits the user requirement most for the feature you are documenting it. Maybe it's two or three, maybe it's all of them
Explanationβ
Explanation documentation details and clarifies a particular topic, providing deep insight into the workings of a feature of Hasura delivered in a long-form format.
Task guidesβ
Task guides complement explanation sections by providing information about how to accomplish specific isolated tasks step-by-step.
Tutorialsβ
Tutorials teach the creation of a larger system based on generalized use-case scenarios. These are generally longer and more involved than task guides and cover the end-to-end creation and setup of a system.
Referenceβ
Reference guides, such as those for the Hasura API, exhaustively cover all possible usages, definitions and edge cases of a feature in a succinct, look-up type format.
The docs contribution processβ
We have a full write-up on the wiki about the docs contribution process, please check it out.
Importantly, the docs team is tasked with maintaining and uplifting the quality of the documentation with every single pull request. Please also check out the docs PR checklist with info about how you can ensure the quality of your docs PR.
Measurement & feedbackβ
The impact of all documentation whether new, changed or existing should be measured with analytics and user feedback tools over time to determine its quality and impact for our user audience.
Next steps...β
After your local environment is set up, feel free to poke around the style guide, explanation of our page structures, and info on working with Docusaurus (our docs framework).