Description
Centralization of sets of rules to follow or informations when writting docs.
Table of contents:
Technical matters:
- General organization / update or create new documents
- Frontmatter for markdown pages
- Links to other parts of the documentation
- How to write comments in markdown files
Content matters:
- Way of writing
- Orthograph / choices of words
- Screenshots: both light & dark versions
- Remark containers
Troubleshooting:
General organization / update or create new documents
Generic procedure to follow
For creating new documents:
- go to Code
- create a new branch
- edit the files, create new ones, add folders, ... all that you need
- once you're done, go to pull request and create a new one with your new branch
- wait (maybe a lot... x) ) for the checks to be done, update if necessary, then wait for feedback of reviewers.
- don't forget to update the topics issue, or tags and kinds files to keep track of the things
- if you put links to non existing pages yet, create a new issue (labelled ToDo) listing all the links to update later (lines, and related page)
Headers hierarchy
The default hierarachy MUST be precisely followed, because it's used as a base to atuomatically build the ToC.
# Page Title
: must be unique in the document. This is name of the page## Section Title
### Subsection Title
- ...
Note: you cannot make "jumps" in the heirarchy, like forgetting ##
on purpose and go straight to ###
. This will cause rendering errors.
Sidebar and automatic "table of contents" (ToC)
See for example this page: https://docs.codewars.com/getting-started/registering/
-
The sidebar on the left is created in the gridsome.config.js document, a the root level.
- How to create it:
- create all the needed files first
- edit gridsome.conifg.js
- add the sidebar name to the frontmatter of all the related documents
- The steps above can actually be done in any order. If something is wrong at some point, the sidebar just doesn't show up in the rendred pages, that's all (hence, it can sometimes be hard to find what the problem actually his... :/ )
- Use the paths of the rendered pages on https://docs.codewars.com/, NOT the actual path of the files in the repo. See the section about links.
- How to create it:
-
The Table of Content (ToC) is automatically created when the page is rendered according to the headers used in the document. Hence this implies some constraints on those headers/titles:
- You have to follow exactly the hierarchy of the headers (see above) otherwise the ToC won't render at all.
- You cannot put links markdowns on them (B4B says: if someone finds a way, I'd be happy to update that! XD )
- Avoid titles ending with colons or things like that
- Choose small titles as much as possible, to avoid things like this... x)
Frontmatter for markdown pages
How to define it
To put at the beginning of the pages, so that the documents are associated with the related "'stuff" (fields are optional):
---
description: ""
kind: reference
topic: markdown
sidebar: docs
prev: /docs/writing-content/
next: /docs/settings/
tags:
- docc
- deploy
- short
---
Warnings:
- Don't forget the whitespaces after the colons... XD (
kind:tutorial
doesn't work, butkind: tutaorial
does) - For info about how to build the sidebar, see here.
- As any other links
perv/next
have to be rendered path, not file paths (see links section)
Choosing the right kind of labels for the documentation
See #8 (ext. documentation: https://documentation.divio.com/).
- All available "kinds" defined here.
- All available "tags" defined here.
- All available "topics" defined here (A comprehensive list of "Topics" used in the docs (frontmatter) #108 )
Links to other parts of the documentation
-
External links: just like usual:
[text](https://...)
-
For links to terms of the glossary, use the following syntax:
[text](/glossary/#id)
, where theid
is either the slugifiedterm
itself (lowercased string, replacing whitespaces with hyphens) or theid
filed if manually defined (code file: glossary ; related issue: Complete the glossary (an ongoing comprehensive (?) list) #23 ). -
For other internal links to the docs, use the path of the rendered page (not to be confused with the file path!).
For example, if the Markdown file is atcontent/foo/bar.md
, its (rendered) path is/foo/bar/
.
Exceptions areindex.md
files: they are treated likeindex.html
socontent/foo/index.md
is at/foo/
.file:
docs/content/references/markdown/extensions.md
link;[check the Codewars Mardown extensions](/references/markdown/extensions/)
file:
docs/content/references/markdown/index.md
link;[check the Mardown reference page](/references/markdown/)
-
Alternative syntax using "references", for internal or external links:
It's possible to definereferences
so that the complete path of the link doesn't decrease the readability of the text:link:
[check the Codewars Mardown extensions][mark-ref]
reference:[mark-ref][/references/markdown/extensions/]
put preferably all the references at the end of the file (see example here)
If you need to put comments in the file, not visible in the rendered page
Use regular html comments:
<!---sqrtgstg--->
Way of writing
#74 (comment): Inspiration can be taken from Google's developer documentation style guide.
Some points to kee in mind:
- Write with translation and a global audience in mind to make it easy to understand by non-English speakers.
- Make clear who's performing the action
- Use second person. "It's generally best to avoid our."
- Use descriptive link text that is helpful to the reader
- Put conditional clauses before instructions, not after
Orthograph / choices of words
- website name:
Codewars
, not "CodeWars" - plurals: use
Kata
,Kyū
,Dan
,Kumite
(Kata/Katas: defining the plural to use in the docs #63) - terms to avoid: codewarrior(s), prefere
user(s)
Screenshots: both light & dark versions
Pictures can be stored in a subdirectory if needed. Preferably called img
if used.
Related code:
<ThemedImage
alt="Follow Button"
sources={{
light: require("./img/follow_light.png").default,
dark: require("./img/follow_dark.png").default,
}}
/>
Remark-container to support callouts
See #164
Documentation: See https://gridsome.org/plugins/gridsome-plugin-remark-container
Syntax
:::keyword optional_title
some content
:::
Examples of info boxes (that's how they look at the moment of writing, but they can be modified, extended, or styling can be changed), with in order: tip
, note
, details
, important
, warning
, danger
Troubles with the linter/rendering engine
Problems with correct wording considered incorrect by the linter
(related: #7)
If you need to temporarily deactivate the linter (ex: "the data is built in suach a way..." raises an error asking to change for built-in
), use this:
<!--- textlint-disable -->
...(your problematic paragraph here)
<!-- textlint-enable -->
or
<!--- For false positive "built in" -->
<!--- textlint-disable terminology -->
...
<!--- textlint-enable terminology -->
Usual mistakes to check when the rendering doesn't work
-
If you get everything in red in the pull request, here are some things to check:
- Click
Details
on the result of the linter check to see if some words or expressions are considered invalid (see above)
- Click
-
If the linter is ok but not the other checks, verify that
- the different headers are consistent through the page:
- you need to have
#
as title - you cannot "jump" in the hierarchy, if you have
###
, you must have#
and##
somewhere before
- you need to have
- the different headers are consistent through the page:
-
If all checks are green and the ToC or the sidebar aren't showing up:
- check your headers hierarchy
- check how to build the sidebar