How to write documentation - SethKitchen/ThreeMojo GitHub Wiki

How to write documentation

Documentation in this project follows four standards. This guide says what each one asks of you. make docs-check enforces the rules a tool can check.

Where documentation lives

Document Location Published as
README README.md The repository front page
Contributing guide CONTRIBUTING.md GitHub's contributing link
Wiki pages docs/wiki/*.md The GitHub wiki, on every push to main
API reference Docstrings in the source make docstrings audits them

Edit wiki pages in docs/wiki/, never in the wiki itself. The CI workflow overwrites the wiki from the repository. This is the DocOps rule: documentation is code, reviewed and tested with the code.

Choose the page type

Follow Diátaxis. Each page has one job:

Type Job Name pattern
Tutorial Teach by doing, step by step, with a guaranteed result Tutorial-<goal>
How-to guide Solve one task for a reader who knows the basics How-to-<task>
Reference State what exists and how to call it The feature name
Explanation Say why the design is what it is Why-<topic> or The-<event>

Do not mix the types. A reference page does not teach. A tutorial does not explain the design. Link to the other page instead.

Put the main point first

Use the inverse pyramid. The first sentence of a page says what the page gives the reader. The first sentence of a section states the conclusion. Details and history come after.

Write in Simplified Technical English

Follow ASD-STE100:

  • Write short sentences. Use at most 20 words in an instruction and 25 in a description.
  • Write one instruction per sentence. Use the imperative: "Run make check."
  • Use the active voice and the present tense.
  • Use "must" for a requirement and "can" for a possibility. Do not use "should", "may" or "might".
  • Use one term for one thing. A scene node is a "node". A texture is a "texture", not an "image".
  • Keep paragraphs to six sentences and one topic.
  • Put code, file names and commands in code spans.
  • Write American English: "color", "meter", "center", "gray", "-ize". This applies to code and identifiers too.

Figures

Each feature page has one animated PNG in out/. The file is committed. Name the PNG after the page. Do not name the example program after a package. examples/math.mojo would hide math/. Do not put a gallery of figures on Examples or on Home.

Write the image after the first paragraph:

![A small cube orbits a large cube and passes behind it](out/cubes.png)

The alt text is one short sentence. make wiki-publish copies out/*.png with the pages.

Check the rules

make docs-check

The tool reports each sentence over the limit, each paragraph over six sentences, each forbidden word, and each British spelling. It skips code blocks, tables and headings.

The tool also checks the wiki links. It reports each wiki link to a page or a heading that does not exist. A wiki link is [text](Page), [text](Page#anchor), [text](#anchor), or a link to the GitHub wiki.

An anchor is GitHub's slug of a heading: lower case, with punctuation removed and each space changed to -. A repeated anchor gets the first free -1 or -2 suffix. The check decodes %XX escapes and ignores a link title. It skips fenced and inline code. A fence closes only with its own character, repeated at least as many times as it opened.

Publish the wiki

The CI workflow publishes docs/wiki/ on every push to main. To publish by hand:

make wiki-publish

GitHub creates the wiki repository when someone saves its first page in the browser. That step happens once.

⚠️ **GitHub.com Fallback** ⚠️