Docs Guidelines/How To

[Blind4Basics]

trafficstars

Centralization of sets of rules to follow or informations when writting docs.

Table of contents:

Technical matters:

• General organization / update or create new documents
  • Generic procedure to follow
  • Headers hierarchy
  • Sidebar and automatic "table of contents" (ToC)
• Frontmatter for markdown pages
  • How to define it
  • Choosing the right kind of labels for the documentation
• 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:

• Resolving troubles
  • Problems with correct wording considered incorrect by the linter
  • Usual mistakes to check when the rendering doesn't work

---

General organization / update or create new documents

Generic procedure to follow

For creating new documents:

1. go to Code
2. create a new branch
3. edit the files, create new ones, add folders, ... all that you need
4. once you're done, go to pull request and create a new one with your new branch
5. wait (maybe a lot... x) ) for the checks to be done, update if necessary, then wait for feedback of reviewers.
6. don't forget to update the topics issue, or tags and kinds files to keep track of the things
7. 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.

  1. 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
  2. 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... :/ )
  3. 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.

• 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:

  1. You have to follow exactly the hierarchy of the headers (see above) otherwise the ToC won't render at all.
  2. You cannot put links markdowns on them (B4B says: if someone finds a way, I'd be happy to update that! XD )
  3. Avoid titles ending with colons or things like that
  4. 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, but kind: 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 (#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 the id is either the slugified term itself (lowercased string, replacing whitespaces with hyphens) or the id filed if manually defined (code file: glossary ; related issue: #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 at content/foo/bar.md, its (rendered) path is /foo/bar/. Exceptions are index.md files: they are treated like index.html so content/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 define references 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

https://github.com/codewars/docs/issues/74#issuecomment-661583133: 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 (#63)
• terms to avoid: codewarrior(s), prefere user(s)

Screenshots: both light & dark versions

See #71, #85

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)

• 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

• 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

[Blind4Basics]

possessive/undetermined formulations? What "tone" should we use?

(don't pay too much attention to the title of the message... translation troubles I have...)

The easiest way of getting started is to use our trainer on the dashboard to pick your next kata.

The easiest way of getting started is to use the trainer on the dashboard to pick your next kata.

=> what option should we use?

1. whatever we want?
2. possessive form
3. undetermined/passive form

I personnaly prefer 3. Because when I see possessive forms, I always associate that with advertising... :o (personnal bias, I guess...)

[kazk]

It depends, but I'd avoid "our trainer" in this case. It's obvious that it's Codewars' so it's unnecessary.

[kazk]

We should follow some existing guidelines for general writing style.

I like Google's developer documentation style guide.

• 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

When you're documenting tasks that involve the user interface (UI), focus on the task, not how the user interacts with the UI element. https://developers.google.com/style/ui-elements

[Blind4Basics]

todo:

• [x] add info about the way to create new documents using PR, ...
• [x] sidebar

[Blind4Basics]

to add: https://github.com/codewars/docs/issues/19#issuecomment-720920787

[hobovsky]

Examples of info boxes:

In order: tip, note, details, important, warning, danger

That's how they look at the moment of writing, but they can be modified, extended, or styling can be changed.

[Blind4Basics]

to add: https://github.com/codewars/docs/pull/280

[Blind4Basics]

todo: prune these guidelines from what has become useless since the migration to Docusaurus and build a meta/docs-guidelines.md

see #286