Skip to content

Contributing to the wiki

This wiki is a git repository of Markdown files. Every page has an edit button in its top right corner, and using it is the whole workflow.

Fix a page in your browser

  1. Click the edit button on the page. It takes you to that page's source file in GitLab.
  2. Edit it. GitLab creates a branch for you.
  3. Commit with a short message saying what you changed.
  4. Open a merge request.

A maintainer reviews it and merges. Once merged, the site rebuilds and publishes itself.

You need an account on git.obarun.org, and registration is open.

Small corrections are the most valuable

A wrong command, a dead link, a path that changed, an option that no longer exists. These are what make a wiki untrustworthy, and each one takes two minutes to fix. You do not need to write a whole page to be useful.

Work locally

For anything larger than a paragraph:

$ git clone https://git.obarun.org/obdev/wiki.git
$ cd wiki
$ python -m venv .venv && .venv/bin/pip install -r requirements.txt
$ .venv/bin/mkdocs serve -f src/mkdocs.yml

mkdocs serve gives you the site at http://127.0.0.1:8000 and reloads as you save.

Before you open a merge request:

$ .venv/bin/mkdocs build -f src/mkdocs.yml --strict

--strict fails on any broken internal link or page missing from the navigation. The pipeline runs the same command, so a build that passes locally passes there.

Adding a page

  1. Create the file under src/docs/<section>/.
  2. Add it to the nav: block in src/mkdocs.yml. A page that is not in the nav fails the strict build.
  3. Link to it from its section index, in the card grid.

What belongs here

Yes:

  • Anything specific to Obarun: 66 usage, the Obarun tools, the repositories, installation.
  • Recipes: the sequence of commands that actually solved a real problem.
  • The gotchas. Things that cost you an afternoon are the most valuable pages in any wiki.

No:

  • Anything that works the same as on Arch. Link to the Arch Wiki instead of copying it. A copied page goes stale and then actively misleads.
  • The exhaustive reference for 66. That is docs.obarun.org, generated from the source. Link to it.

House style

  • English, and plain English. Many readers are not native speakers.
  • Verify before you write. Run the command on a current system. Do not copy a command from an old page and assume it still works, and do not write from memory.
  • No invented facts. No version numbers, dates or figures you have not checked.
  • Show the prompt. # for root, $ for an unprivileged user.
  • Prefer the shortest correct thing. A page nobody finishes reading helps nobody.
  • Use admonitions for what matters: !!! warning for what can break the system, !!! note for asides.

Reporting a wiki problem you cannot fix

Open an issue on git.obarun.org/obdev/wiki, or write to wiki@obarun.org. Saying which page and what is wrong is enough. Someone else can write the fix.