General editing rules and tips
The main goal is to make it as easy to understand as possible. Imagine that you teach your 9 year old nephew how to program. When you teach someone a new topic, assume that the student does not know anything about it yet.
Use images, GIFs, video links
Do not flood the students with pages full of text only. Roughly 1/3 of the content should be in a graphical form. Prefer showing, not only talking about it.
Be careful with links
There is a known issue with a trailing slash at the end of page URL. By default, we assume, that our URLs end with a slash.
Let's say that you have a following folder structure:
When you open the
std/index.mdx, it will be used as a default document from that directory, with following url:
https://cpp-lang.net/docs/std/ <-- notice the trailing slash
To add a link to
std/math/functions.mdx you'll have to use:
<a href="math/functions">Math functions</a>
because we're already inside of the
docs/std/ folder, because of the trailing slash.
That leads to an unexpected behavior, if you want to reference a document from the same directory,
when the referencing document is not a default document.
Lets now consider the following folder structure:
If you open the
foo document, the URL will be:
https://cpp-lang.net/docs/foo/ <-- notice the trailing slash!
This creates a false impression that the
foo is a directory, which it isn't.
If you want to reference
bar from the
foo document, you'll have to start at the parent directory (docs):
Tags help people find the topic they're interested in. Please add tags to the document metadata.
tags: [tag1, tag2]
Use admonitions (notes, tips, cautions, dangers)
To create a fancy looking admonition, use the following syntax:
This is a tip
This is a note
This is an important note
This is a caution note
This is a danger note
This section requires improvement. You can help by editing this doc page.