Documentation Guidelines¶

This document establishes standards for writing and maintaining documentation in this dotfiles repository.

Philosophy¶

1. Concise over comprehensive — Users scan docs, they don't read novels
2. Examples over explanations — Show, don't tell
3. Actionable over theoretical — Every section should help someone do something
4. Maintain one source of truth — Don't duplicate; link instead

Consistency Rules¶

To prevent information gaps, follow these three golden rules:

1. Overview in README: Every significant feature or tool MUST be at least mentioned in README.md. It is the entry point.
2. Detail in Docs: Every feature mentioned in the README MUST be fully explained in a dedicated file in docs/. The README is for what; the docs are for how and why.
3. No Orphans: There should be nothing in the README that isn't fully expanded upon in the official docs. If it's important enough for the README, it's important enough for a detailed explanation.

File Naming & Structure¶

CLI Documentation Standards¶

CLI documentation should describe command usage, subcommands, and examples.

Location¶

• Main page: docs/reference/CLI.md
• Source: dots alias definitions or mise.toml

Format¶

• Use standard help output format where possible
• Include examples for common use cases
• Document shortcuts and aliases

Testing¶

• Preview locally: mise run docs:serve

See CLI Reference for current documentation.

Markdown Style Guide¶

Headers¶

• Use # for document title (one per file)
• Use ## for major sections
• Use ### for subsections
• Add --- horizontal rules between major sections for visual separation

Code Blocks¶

Always specify the language for syntax highlighting:

# Good
mise run doctor

Use inline backticks for: - File names: dot_aliases - Commands: mise run install - Variables: $DOTFILES_DIR - Tool names: fzf

Tables¶

Use tables for structured data:

| Tool | Purpose | Replaces |
|------|---------|----------|
| eza  | Better ls | ls |
| bat  | Better cat | cat |

Links¶

• Use relative links for internal docs: [Tools](../reference/TOOLS.md)
• Use descriptive link text: [Customization Guide](../guides/CUSTOMIZATION.md) not [click here](../guides/CUSTOMIZATION.md)

Advanced Features (MkDocs Material)¶

• Mermaid Diagrams: Use ```mermaid blocks for flowcharts, sequences, etc.
• Code Annotations: Use (1) in code blocks and attach descriptions using 1. Explanatory text.
• Admonitions: Use !!! note "Title" or !!! warning blocks for callouts.
• Content Tabs: Use === "Tab Title" for multi-distro or multi-language instructions.

Emoji Usage¶

Limit emoji usage to "professional" ones that serve a functional purpose. Avoid purely decorative "flair" emojis.

Allowable Professional Emojis: - ✅ — Success / To-do completed - ⚠️ — Warning / Caution - ❌ — Error / Failure - ℹ️ — Information - 💡 — Tip / Rationale - ⭐ — Highlight / Feature - ➔, ➜, ➞ — Action / Transition

Guidelines: - Use emojis only if they improve scannability or highlight critical information. - Do not use emojis in headers (e.g., ## ✨ Features should be ## Features). - Do not use decorative emojis like 🚀, 🔧, 🧠, 📁 for visual flair.

When to Update Documentation¶

Always Update Docs When:¶

• Adding a new tool to mise.toml
• Adding or changing aliases
• Changing directory structure
• Adding new configuration files
• Breaking changes to existing behavior
• Fixing a bug that users might encounter

Update Locations:¶

Inline Comment Standards¶

Config Files (zshrc, aliases, etc.)¶

Use section headers with box-style comments for major sections:

# ═══════════════════════════════════════════════════════════════
# Navigation Aliases
# ═══════════════════════════════════════════════════════════════

Use # comments for explanations:

# Smart wrapper: no args = modern tool, with args = standard command
ps() {
    if [ $# -eq 0 ] && command -v procs >/dev/null; then
        procs
    else
        command ps "$@"
    fi
}

What to Comment¶

• Why, not what — The code shows what; comments explain rationale
• Non-obvious behavior or edge cases
• Links to upstream docs for complex options
• Version requirements or compatibility notes

What NOT to Comment¶

• Self-explanatory code: alias g='git' # git alias ← unnecessary
• Obvious groupings that headers already explain

Document Templates¶

Troubleshooting Entry¶

### Issue: [Brief Description]

**Symptoms**: What the user observes

**Cause**: Why this happens

**Fix**:
1. Step one
2. Step two

**Prevention**: How to avoid this in the future

Tool Entry¶

### toolname

| | |
|--|--|
| **Replaces** | `original-command` |
| **Category** | Files / System / Git / etc. |
| **Homepage** | https://... |

Brief description of why this tool was chosen.

**Key Commands**:
- `toolname --help` — Get help
- `toolname common-use` — Common usage

**Configuration**: `~/.config/toolname/config` or "None"

Changelog Entry¶

## [X.Y.Z] - YYYY-MM-DD

### Added
- New feature or file

### Changed
- Modified behavior

### Fixed
- Bug fix

### Removed
- Deprecated feature

Review Checklist¶

Before committing documentation changes:

• Spell-checked
• All links work
• Code blocks have language specified
• Tables render correctly
• No outdated information
• Changelog updated if applicable
• Consistency Check: New features added to both README (brief) and Docs (detail)

Link Checking¶

This repository enforces valid links via CI.

• Tools: markdown-link-check and mkdocs-linkcheck-plugin runs in CI.
• Local Check: Run mise run validate-links before pushing.
• Strictness: Broken internal links will fail the build. External links may warn.