mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-16 01:44:03 +03:00
494e270227
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/6059 GitOrigin-RevId: c527d01b7af8ef98fa3859930115ec44d993e444
31 lines
1.6 KiB
Plaintext
31 lines
1.6 KiB
Plaintext
---
|
|
title: General
|
|
description: General documentation style
|
|
sidebar_position: 1
|
|
keywords:
|
|
- hasura
|
|
- style
|
|
- general
|
|
slug: general
|
|
---
|
|
|
|
# General Style Points
|
|
|
|
- Try to include a `TL;DR` block for feature documentation at the top of the doc to summarise it as much as possible.
|
|
- Hasura features should be proper noun _title case_ to differentiate from any other uses of the word Eg: Console,
|
|
Metadata, Migrations, Actions, Events, etc.
|
|
- Keep in mind you are trying to write for beginner, intermediate and advanced users.
|
|
- All lines in markdown should break at **120 characters** for better readability in IDEs. 120 is useful because it
|
|
still allows side-by-side editing on most screens and closely matches the line length of the final output page at max
|
|
width.
|
|
- Add appropriate cross-links in content to assist users.
|
|
- If you refer to some functionality that is documented in some other docs page, add a link to that page.
|
|
- If you have a statement like "create a relationship between tables X and Y ...", make "create a relationship"
|
|
a link to the `Create relationships` page.
|
|
- 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.
|
|
|