Skip to content

Writing Guide

A few principles to keep the wiki consistent and easy to read.

Important

  • For mod devs

Writing Mod Documentation

Documentation exists to help players understand and use your mod. The goal is not to create the longest wiki possible, but to provide accurate and useful information.

Every Mod Is Different

There is no single correct way to structure a mod page.

A small utility mod may only need an overview page and a short configuration page. A larger content mod may require feature pages, screenshots, guides, changelogs, and extensive navigation.

Templates should be used as a starting point, not copied blindly.

Always structure documentation around the needs of your mod rather than forcing your mod into a predefined structure.

Tip

Ask yourself: "What information would a player look for first?" Organize pages around that answer.

Write for Players

This wiki is intended to document mods, not development processes.

Avoid including:

  • Personal design notes
  • Future ideas that are not implemented
  • Internal code details
  • Developer discussions
  • Unreleased features

Players visit the wiki to learn what a mod does and how to use it. Keep documentation focused on information that is relevant to them.

Accuracy Is More Important Than Detail

Not every feature requires a lengthy explanation.

A feature may only need a single sentence if its behavior is obvious.

However, every description should accurately reflect what happens in-game.

Short documentation is perfectly acceptable as long as it remains correct.

When referencing another mod, always include a link to its official page whenever possible.

Preferred sources:

  1. CurseForge
  2. Modrinth
  3. Official project website

This allows readers to quickly find the referenced mod and learn more about it.

Example:

For detailed loot information, consider using [EMI Loot](https://www.curseforge.com/minecraft/mc-mods/emi-loot).

Avoid Duplication

Some projects already maintain their own documentation elsewhere.

If a separate wiki already exists, it is acceptable to link to that documentation rather than rewriting everything.

However:

  • The overview page on this wiki should still be completed.
  • Important information that is missing from the external documentation may be documented here.
  • Information should not exist in two places without a good reason.

A good rule to follow is:

No duplication, and nothing important missing.

The purpose of this wiki is to improve accessibility, not to create multiple competing copies of the same documentation.

Final Checklist

Before publishing documentation, verify that:

  • Information is accurate and matches the current version of the mod.
  • External references use proper links.
  • Pages are organized in a way that makes sense for the mod.
  • Players can quickly find the information they need.
  • Documentation focuses on the mod rather than the development process.

Good documentation should feel invisible. Players should be able to find what they need without thinking about how the wiki is organized.

Note

  • Other important rules everyone should know about

Accuracy and versioning

Always document what is currently present in the supported Minecraft version.

Do not assume a feature still exists because it existed in an older version.

Before documenting a mechanic:

  • Check the current mod version
  • Verify the feature in-game, official documentation, source code, or changelogs
  • Avoid relying on memory alone

If you are unsure:

  • Mark the information as unverified
  • Open an issue asking for confirmation
  • Do not present guesses as facts

When discussing removed or legacy features, clearly label them with the version they existed in.

Sources

Whenever possible, include a source for technical information.

Good sources:

  • Official documentation
  • Source code
  • Changelogs
  • Developer statements
  • In-game testing

Avoid:

  • Old YouTube tutorials
  • Outdated wiki pages
  • Forum posts without confirmation
  • Information remembered from older versions

Note

Old YouTube tutorials/wikis/forums can still be linked if not outdated by newer mod versions.

Legacy content

Older mechanics can still be documented if they are historically relevant.

However, they must be clearly separated from current information.

Example:

Current Mechanics ...

Legacy Mechanics (1.16) ...

Tone

  • Write for someone who has never seen the mod before
  • Be direct — "Click X" not "You may want to consider clicking X"
  • Use second person: "you", not "the player" or "the user"
  • Don't assume prior knowledge unless the page is explicitly advanced

Page structure

Every mod page should follow this order:

  1. Short description — one sentence, what the mod does
  2. At a glance callout — loader, MC version, download links
  3. Overview — a paragraph or two explaining the mod in more depth
  4. The actual content — installation, config, whatever the page is about

Callout boxes

Use these to draw attention to important things:

!!! note "Note title"
    General information worth highlighting.

!!! tip "Tip title"
    A helpful hint or shortcut.

!!! warning "Warning title"
    Something that can go wrong or break things.

!!! danger "Danger"
    Data loss, irreversible actions, serious issues.

!!! info "Info"
    Neutral extra context.

Tabs (for multi-platform steps)

Use tabs when the same steps differ by platform or loader:

=== "Fabric"
    1. Install Fabric API
    2. Drop the jar in mods/

=== "Forge"
    1. Drop the jar in mods/
    2. No extra dependencies needed

Code blocks

Always specify the language for syntax highlighting:

```toml
server_url = "https://example.com/pack.zip"
```

```bash
mkdocs serve
```
  • Link to related pages generously — it helps navigation
  • Link mod names to their overview page on first mention per page
  • External links: always link to the official Modrinth or CurseForge page, not third-party mirrors

Images

  • Put images in docs/assets/mods/MOD-NAME/
  • Use descriptive filenames: config-screen.png not screenshot1.png
  • Add alt text: ![The configuration screen showing all available options](../assets/mods/example/config-screen.png)

Screenshots beat paragraphs

When explaining a user interface, configuration screen, structure, or visual mechanic:

Prefer one screenshot over three paragraphs of description.

Images often communicate information more clearly than text.

Stubs and "help wanted"

If you're creating a page but can't fill it all in yet, add this at the top:

!!! note "Help wanted"
    This page is incomplete. Click **Edit this page** to contribute!

This signals to other contributors that the page needs work.