This structure lets the reader understand what the module is for before diving into the technical configuration.
Reference page
This is the documentation's reference page for integration and development
Writing style
The documentation is an essential part of DraftBot: it gives every user a good experience of the bot. It matters that they can find answers to their questions easily and on their own.
Here are a few pieces of advice for improving the quality of your writing:
- Clarity and concision: Use clear and precise vocabulary, matching DraftBot's wording as closely as possible. Avoid needless jargon and long sentences. Your goal is to make the information easy for the reader to understand.
- Stay considerate: avoid subjective expressions such as "simply", "just", "obviously" as much as possible. Keep in mind that we all have different experience and backgrounds. These words add no useful information and can sometimes come across as dismissive or hurtful, particularly to people discovering Discord or starting out with DraftBot.
- Use informative language: the point of the documentation is to convey information and knowledge about using the bot. To match that, stay neutral and objective as much as possible, without trying to convince, entertain or push choices or actions.
- Consistency: keep the style, tone and terminology consistent throughout the documentation. This maintains a smooth, professional reading experience. To that end, use the declarative form in the active voice as much as possible, in the present tense in most cases. Exceptions and departures can of course be made depending on the situation, to come back to an earlier explanation or to raise a future possibility.
Writing rules
A user-oriented introduction
When writing a page, always start with a presentation of the system from the user's point of view.
When a server manager decides to enable a system, they always put themselves in their members' shoes. If they are convinced, they will move on to setting it up.
Recommended structure of a module page
To keep the whole documentation consistent, follow this structure when writing a module page:
- User view: start by explaining what an ordinary member sees and does (user commands, visible features)
- Administrator view: explain the management features and admin commands
- Configuration: detail the configuration options (through the "Panel" / "/config command" tabs)
- Advanced use cases: migrations, tips (optional)
Premium features
When you want to indicate that a feature is premium, do not put it in the title or in the feature's description. Use an info hint instead; several wordings such as these work well:
Limit extended by premium
You can run up to 3 giveaways at the same time. Premium 
servers have no limit.
Premium feature
This feature is reserved for premium servers.
Premium feature in a table
Features marked with the symbol are reserved for premium servers.
Screenshots
They are essential for illustrating the documentation and giving it room to breathe. To stay in harmony with the rest of the documentation:
- Prefer wide shots with no editing of the screenshots.
The necessary edits, such as cutting out or cropping the screenshots, are done by a writing referent once the writing and the corrections are finished. - Use the Discord theme called "Dark" exclusively.
Links to the panel
Let the user reach the relevant page of the panel every time the page changes:
- At the top of the section concerned
- In every section concerned (even if it comes up several times on the same page)
Configuration from the Panel and /config
Always put the "From the panel" choice first rather than "Using the /config command", to keep the pages consistent so that members do not have to look for it.
This is for configuring from the panel.
Default values and behaviors
Always give the default values when a feature offers any:
Recommended format:
- Directly in the description: "15 to 25 XP by default"
- In brackets for options: "configurable 100-1500"
- In an info hint for complex behaviors
Example:
Each message grants a **random** amount of experience between two values you configure (**15 to 25 XP** by default).
Specific behaviors and edge cases
Some features behave in specific ways in particular situations (edge cases). Document them clearly to avoid confusion:
Recommended format:
**Specific behaviors:**
- **Name of the case**: a clear explanation of the behavior, with a concrete example if needed.
- **Another case**: description…
Example:
- **Skipping levels**: if a member skips several levels at once (through \</adminxp add>), they receive **every reward** of the intermediate levels. For example, if a member goes from level 5 to 25, they will receive the rewards of levels 10, 15, 20 and 25.
Required Discord permissions
When a feature requires specific Discord permissions, document them in a warning hint:
Required permissions: to send announcements, DraftBot needs the following permissions in the chosen channel: View Channel, Send Messages, Embed Links and Attach Files. If these permissions are removed, announcements are disabled automatically.
Good practice:
- List every required permission
- Explain the consequences if the permissions are missing
- State whether the system disables itself automatically or returns an error
Navigation icons
Every page of the documentation (apart from a few) has to set an icon through navigation.icon.
Two icon libraries are used:
twemoji: only for feature pages (Member welcome, Engagement, Games & events, Community, Security, Utilities) and the home/installation pages.material-symbols: for every page of the documentation.
Examples
navigation.icon: material-symbols:edit-document-outline
navigation.icon: material-symbols:edit-document-outline
Multilingual structure
The documentation exists in French and in English. French is authoritative: every page is written in French first, then translated.
Where to put a file
French pages live under docs/fr/, English ones under docs/en/.
File and folder names are in English and identical in both languages —
that is what pairs a page with its translation. A French page is therefore
called docs/fr/3.engagement/0.levels.md, not 0.niveaux.md.
The numeric prefixes determine the display order in the menu.
Declaring a page's address
A page's address no longer comes from its file name but from its frontmatter:
---
title: Levels
slug: /engagement/levels
---
The slug is the full path, without the /docs/en prefix. It has to
start with the slug of the _dir.yml file of its folder, minus its
/_dir suffix.
_dir.yml files carry one too, ending in /_dir:
slug: /engagement/_dir
title: Engagement
Images
A page's images live in the assets/ folder of its category, in a
subfolder named after the page:
docs/fr/3.engagement/
├─ assets/levels/panel.png
└─ 0.levels.md 
Checking your work
node scripts/check-translations.mjs # slugs, duplicates and up-to-date translations
node scripts/check-links.mjs # missing images and internal links
Translations
You do not have to translate anything yourself. When a French page changes, a translation pull request is opened automatically — it needs to be reviewed, not written. While it awaits review, the English documentation displays the up-to-date French version rather than an outdated translation.
Excluding a page from translation
A page that is not meant to exist in English carries translate: false
in its frontmatter:
---
title: 2026
slug: /annexes/changelog/2026
translate: false
---
It then drops out of the list of pages to translate. This is the case of the changelog, which stays in French.
This key does not propagate: putting it in a _dir.yml only excludes that
file, not the pages of the folder. Every page to exclude has to carry it.
Structuring tools
Organize your content logically. Use headings, subheadings, tabs and screenshots so that it is easy to follow. Below are all of the structures available.
Headings
Be careful not to nest headings inside block elements (such as collapsible menus or tabs)!
Basic markdown
Bold
Italic
Bold italic
Bold italic
Strikethrough
Code
"Quote"
Ctrl A + C
Emojis & mentions
Text emoji: 
Character emoji:
Custom Discord emoji: 
Animated custom Discord emoji: 
Command mention: /command
Channel mention: channel
Bullets & lists
- Bullet 1
- Bullet 2
- Bullet 3
- Bullet 3.1
- Bullet 3.1.1
- Bullet 3.1
- Num 1
- Num 2
- Num 3
- box 1
- box 2
Information hints
Hints highlight important information. Choose the type according to the context:
A nice, positive little piece of information
A nice, informative little piece of information
A moderately nice little warning
A not-so-nice little piece of information
Several hints in a row: only use several consecutive hints if the pieces of information are of different types (an info followed by a warning, for example). Otherwise, gather the information in a single hint with bullets.
Table
Tables are essential for comparing options or listing features in a structured way.
Use a table to:
- Compare several types of options
- List commands with their descriptions
- Present customization variables
| Curve | Difficulty | Description |
|---|---|---|
| Constant | Fixed | Every level requires exactly the same amount of XP |
| Linear | Moderate increase | Linear progression |
| Exponential | Fast increase | Exponentially increasing difficulty |
Collapsible
Tabs
Information 1
::tabs
::tab{ label="Tab 1" }
Information 1
::
::tab{ label="Tab 2" }
Information 2
::
::tab{ label="Tab 3" }
Information 3
::
::
Card
