Contributing to the Console9 Wiki
Content guidelines, style rules, front matter reference, and submission process for contributing to the Console9 Wiki.
How to write, format, and submit content for the Console9 Wiki.
Content Types
The Console9 Wiki uses the Diataxis documentation framework. Every article belongs to one of these content types:
| Type | Purpose | Title pattern | Location |
|---|---|---|---|
| How-to | Task recipe — fastest path to a result | "How to {verb} with {Tool}" | /articles/{tool}/how-to/{slug}/ |
| Tutorial | Guided lesson — build understanding | "{Tool} tutorial: {topic}" | /articles/{tool}/tutorials/{slug}/ |
| Troubleshooting | Error diagnosis and fix | "{Tool}: {exact error message}" | /articles/{tool}/troubleshooting/{slug}/ |
| Reference | Lookup table for flags, directives, options | "{Tool} {scope} reference" | /articles/{tool}/references/ |
| Explanation | Conceptual article or comparison | "{Tool A} vs {Tool B}: {criterion}" | /articles/{tool}/explanations/{slug}/ |
| Snippets | Copy-paste-ready commands | "{Tool} command snippets" | /articles/{tool}/snippets/ |
| Best practices | Opinionated recommendations | "{Tool} best practices" | /articles/{tool}/best-practices/ |
| Guide | Multi-tool walkthrough | "How to {goal} with {Tool A} and {Tool B}" | /guides/{slug}/ |
Writing Style Rules
Voice and Mood
Use active voice as the default. The subject performs the action.
- Active: "Rsync copies files from the source to the destination."
- Passive (avoid): "Files are copied from the source to the destination."
Use imperative mood for instructions. Give direct commands without hedging.
- Imperative: "Open the config file."
- Avoid: "You should open the config file."
Sentence Construction
Target 12–20 words per sentence. Never exceed 30 words.
Start each sentence with the subject or the action. Never start with filler words or subordinate clauses.
Never use these words or phrases: "basically", "simply", "just", "actually", "in order to", "please note that", "it is important to note", "let's", "we will explore", "powerful", "robust", "seamless", "leverage", "utilize".
Paragraph Construction
Each paragraph expresses one idea. Structure as: claim, evidence, implication. Target 2–4 sentences per paragraph.
Start every paragraph with a topic sentence that names the tool and states the core claim. This sentence is the primary signal for AI retrieval systems.
Every paragraph must be independently understandable without requiring the reader to have read prior sections.
- Name the tool in every paragraph's first sentence.
- Use full proper names on first mention within each section: "Cross-Origin Resource Sharing (CORS)" then "CORS" thereafter.
- State relationships explicitly: "Logrotate relies on cron to trigger rotation" — not "They work well together."
- Include semantically related terms naturally within each section to create richer vector embeddings.
Punctuation
- Use the Oxford comma: "files, folders, and symlinks".
- Use em dashes (—) with no spaces for parenthetical information.
- Use en dashes (–) only for ranges: "ports 8080–8090".
- Every complete sentence ends with a period, including bullet points.
Front Matter Reference
Every file uses TOML front matter enclosed in
+++ delimiters:
| Field | Required | Description |
|---|---|---|
identifier | Yes | MD5 hash of the file's relative path from the content root |
parent | Yes* | The
identifier of the parent
_index.md file. *Omit for root nodes. |
kind | Yes | "category" for
_index.md files with children;
"article" for content pages |
type | No | Diataxis content type:
"how-to",
"tutorial",
"troubleshooting",
"reference",
"explanation",
"snippets",
"best-practices". Omit for category pages. |
url_path | Yes | The page URL. Pattern:
/wiki/articles/{tool}/{type}/{slug}/ |
title | Yes | Page title — under 60 characters, includes the tool name |
excerpt | Yes | 120–160 characters describing what the page delivers |
published | Yes | Publication date in
YYYY-MM-DD format |
updated | Yes | Last update date in
YYYY-MM-DD format |
tags | Yes | Array of lowercase, hyphenated tags: tool name, platform, problem domain |
applies_to | No | Target platforms:
"Linux, macOS",
"Windows",
"All platforms" |
source | No | Path to the original source file |
[cover] | No | Cover image block with
slug (2–4 words, starts with tool name) and
lines (1–3 lines, under 20 chars each) |
Code Block Rules
- Always specify the language:
```bash,```nginx,```php,```python. - Show the command AND expected output when the output is meaningful.
- Use consistent placeholder conventions:
{YOUR_DOMAIN},example.com(RFC 2606),203.0.113.x(RFC 5737),user@host.
Submitting Changes
- Fork the repository.
- Create a branch for your changes.
- Write or edit content following the guidelines above.
- Verify that all code blocks have language labels.
- Verify that front matter fields are complete and correctly formatted.
- Submit a pull request with a description of the changes.