-
Notifications
You must be signed in to change notification settings - Fork 2.8k
How to write docs pages
This page explains how to write docs pages so that we have a consistent structure across our whole documentation.
Before you start writing, it's important to get a comprehensive understanding of the problem at hand, the audience, as well as the structure.
It's crucial that you understand the problem at hand. If there's a Github issue for it, read through it carefully. Look at examples if they are provided. And ask questions if you're not clear on why this is an issue.
Questions:
- Why is there a change necessary?
- What are users currently struggling with?
It's important to understand the audience of the new docs piece. Try to understand what they're trying to achieve and why they might currently run into issues.
Try to assess what percentage of users are in need of this change. This will help you identify the exact structure and content to add.
Questions:
- Who will read the new page / the addition?
- What are they trying to achieve?
Do some research on what the solution could look like. Sometimes a solution is provided in the issue. Keep in mind that this solution might be outdated, so you should do the research in any case.
Sometimes, the issue at hand is specific to technologies used by Hasura, such as Postgres. In this case, you'll find answers very easily by googling the problem. If the issue is Hasura specific, you might find the solution on other technical content, such as YouTube videos or blog posts.
Questions:
- How can I solve the problem at hand?
- What could the solution look like?
If you can't find the solution to the problem in your research, consult one of the Hasura engineers, they'll be happy to help you out.
Once you have all the necessary information and gathered the actual content, you can start developing a spec.
The first thing to be considered is the weight of the addition. The assessment of the audience will give you an idea of how important the new addition is and will help you decide what form the addition should be. It should be considered how will users find this content when they need it, both via navigation and search.
Questions:
- Should this be a new page?
- Should this be an addition to an existing page?
- Should this be a note in an existing section on an existing page?
The next thing you should ask yourself what form the content should have.
Questions:
- Does this go into reference documentation?
- Is this a guide where users can follow along?
Reference documentation is meant to provide information on the functionalities of Hasura. In includes the following:
- Description of features with corresponding examples
- Information on how Hasura works underneath
An example of a reference page can be found here.
A guide is a page where a workflow is described. The user can follow a set of instructions to learn how something works. A guide might consist of several features.
Guides usually include a number of steps to achieve a certain goal, with subtitles Step 1: Do a, Step 2: Do b.
An example of a guide can be found here.
Once you think you have a solid spec, talk to an engineer to get this signed off. They might have valuable input as they're very close to the product.
Once you have your spec ready and signed off, you can start developing your solution as explained below.
The following meta information should be added at the beginning of each docs page: description and keywords.
An example:
.. meta::
:description: Data validations in Hasura
:keywords: hasura, docs, schema, data validation
Before the page title, add a reference that can be used to link to this page.
An example:
.. _data_validations:
Note: References can also be added above any title within the docs page in order to link to a specific section directly.
Add the main title for each docs page.
An example:
Data validations
================
Ensure every newly added page has a "Table of contents" section with the appropriate depth.
.. contents:: Table of contents
:backlinks: none
:depth: 2
:local:
Add an Introduction section:
Introduction
------------
In the section, give a short overview of what the page is about.
- Add appropriate cross-links in content to assist users. i.e. if you refer to some functionality that is documented in some other docs page, add a link to that page. e.g. if you have a statement like "create a relationship between tables
X and Y ...", make "create a relationship" a link to the
Create relationshipspage. - Try to make each section within a page self-sufficient. i.e. avoid structuring all pages as step-by-step guides unless it really is the intent. This ensures that we can refer to sections externally (from other docs pages, console, etc.) and expect that the user will be able to follow the section without being lost on the context that was set in earlier sections of the page. Adding statements such as "As we have described in the above section ..." might help to set up the needed context.
- Page titles should be self-sufficient. Users might not have the context of the hierarchy of the page in the docs tree. A user can land on a page via search as well. e.g. Say you are adding a new deployment guide for AWS under
Guides -> Deployment -> AWS. The title of this page should not be justAWSbut insteadAWS deployment guide for Hasura GraphQL engine. It's ok to alias it to justAWSin the sidebar as there the user has the context of the page hierarchy. - Ensure heading underlines are the same length as the headings. Short underlines will throw warnings during builds.
- Use bold in headings in place of string literals for aesthetics (i.e. ** in place of ``).
- The nesting of headings is as follows:
Main page title
===============
First heading
-------------
Second heading
^^^^^^^^^^^^^^
Third heading
"""""""""""""
Fourth heading
**************
When linking to other docs pages, use references (:ref:) rather than relative links in order to avoid broken links.
An example:
:ref:`data validation <data_validation>`
In this example, data validation is the link text, and <data_validation> is the reference to which the link will point.
When linking to external pages, make sure to add a double _ in the end to avoid Duplicate explicit target name warnings.
An example:
Google <https://www.google.com/>__
Note: If you link to an external resource, make sure to link to the most current version of the same, e.g. https://www.postgresql.org/docs/current/intro-whatis.html rather than https://www.postgresql.org/docs/9.6/intro-whatis.html.
You have the understand the whole overview(the tone, the aim, the audience, the approach) of the docs, so you can come up with an image that properly references the context of the docs.
For example:
- If you need to add an image to a part in the getting started guide, make sure it's a full image instead of a cropped image. A full image is better so as to make it easier for beginners to get through.
- If you need to add an image in any of the deployment guides, you have to highlight little details that are very crucial to what you are aiming for.
- If the image is too big and you can't take a proper screenshot or you can't reduce it(so it won't be too tiny). You can just get a screenshot of the most important details on it.
Before adding images to docs, first, compress them via some tool to ensure users don't have to unnecessarily download more data than needed. There are several options on how to compress images:
- You can use a website like www.tinypng.com (
tinypng-cli). - You can use a script like this. Note: You need to have Ruby installed to use this script.
Sometimes you can compress images by over 75% without losing any visible quality.
Add images using the thumbnail directive to allow click-to-zoom.
An example:
.. thumbnail:: /img/graphql/manual/schema/validation-add-check-constraint.png
:alt: Add check constraint
:width: 700px
- Add an
:alt:tag for all images - To adjust the image size, use the
:width:tag
If you have screenshots in your docs page and you want to emphasize something, please use this colour code: #ec1c74.
Generally, if you want to show selecting something, use borders. If you want to show clicking on a button, use arrows.
A note can be added in order to draw attention to something like limitations or to link to external reference documentation. It has the title "Notes".
An example:
.. note::
Please checkout the [Postgres documentation](https://www.postgresql.org/docs/current/functions-comparison.html) for more information.
An admonition is the same as a note, but its title can be defined.
Add an admonition as follows:
.. admonition:: Supported by
Scheduled triggers are supported by `v.1.3.0` and above.
Note: Make sure to place the note/admonition in a place where the user will see it at the appropriate time.
While adding code blocks ensure the right language type is set. Sometimes adding placeholders breaks the language's
syntax in which case you'll have to set the language type to none to avoid warnings during builds.
Our docs have a GraphiQL extension that allows displaying GraphQL requests in the GraphiQL UI.
- Use a tab-width of 2 for nesting the requests and responses for optimal use of the space and maintaining consistency.
- Nest query arguments for logical readability. Unfortunately, GraphiQL prettify does not do a good job of doing this by default.
- Ensure that the order of fields in the responses is the same as in the requests for better readability.
Use it as follows:
.. graphiql::
:view_only:
:query:
query {
author_by_pk(id: 1) {
id
name
}
}
:response:
{
"data": {
"author_by_pk": {
"id": 1,
"name": "Justin"
}
}
}
Run the docs build in the end again with make livehtml and make sure there are no warnings because of duplicate labels etc.
This should help team members and others to understand what to look out for when reviewing docs.
It's very important to take the user's perspective when reviewing docs PRs.
Ask yourself the following questions:
- Who is the typical user that will read this docs page?
- What do they struggle with?
- Does this docs page solve their problems?
- Will the user be able to discover this content via navigation/search?
Check if the content addresses these issues. If you have doubts, write a comment on the PR or discuss on the #docs-and-learn channel on Slack.
Try out the instructions. We only know that something works if we've tried it out. We need to make sure that the content is complete and that there's we didn't forget to explain something that we presume as common knowledge.
Make sure the flow is natural and that the user can go through the instructions without hitting bumps.
Ask yourself the following questions:
- Is the reading flow smooth?
- Can I execute the instructions in the same order as to how they are written?
- Are there any hick-ups while reading or trying things out?
We need to make sure that the structure makes sense. This needs to be checked on two dimensions: the page itself and across docs.
Ask yourself the following questions:
- Does the new docs page's structure make sense in itself?
- Is the new docs page's structure consistent with the rest of the docs?
Compare & contrast with other similar docs pages to make sure the structure is consistent.
Last but not least, we need to check the language. First of all, the grammar must be correct. And second, we need to make sure the language is consistent with the rest of the docs. This involves:
- Using the same terms for concepts across all of the docs
- Keep the tone & formality consistent across all docs
Ask yourself the following questions:
- Are there any typos?
- Are there grammar mistakes?
- Is the language & tone appropriate?
- Is the language consistent with the rest of the docs?