mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-09-17 13:37:26 +03:00
4c66d648c7
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/9923 GitOrigin-RevId: 94038efe5768b63f38dfb447bc315ae5f7185c43
99 lines
3.6 KiB
Plaintext
99 lines
3.6 KiB
Plaintext
---
|
||
sidebar_label: Introduction
|
||
sidebar_position: 10
|
||
---
|
||
|
||
# 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](/contributions.mdx) 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
|
||
|
||
<video controls width="100%">
|
||
<source
|
||
src={
|
||
'https://graphql-engine-cdn.hasura.io/assets/videos/docs/documentation-presentation.mp4'
|
||
}
|
||
type="video/mp4"
|
||
/>
|
||
Sorry, your browser doesn't support embedded videos.
|
||
</video>
|
||
|
||
## 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.
|
||
|
||
:::warning The Rule
|
||
|
||
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](/contributions.mdx##step-1-create-a-new-branch), 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](/checklist.mdx) 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).
|