Skip to content

Contributing to the docs

These pages are for people using Apathia, not for developers. Write in plain words: say what the user sees, what each choice changes, and what can go wrong. No formulas, no code internals.

Where things go

  • User pages: docs/site/pages/. Add each new page to nav in docs/site/mkdocs.yml.
  • Developer docs (docs/*.md) and design specs (docs/specs/) are not published.
  • Build locally:
pip install -r docs/requirements.txt
mkdocs build --strict -f docs/site/mkdocs.yml   # or: mkdocs serve -f docs/site/mkdocs.yml

--strict fails on broken internal links and pages missing from the menu, as the docs check on pull requests does.

Style

  • Short sentences. Explain any jargon in one plain line the first time.
  • Say exactly how a setting changes the setup and the trades: more or fewer signals, earlier or later, more or less risk.
  • Describe risks and give warnings; never forbid. No promised returns, no "guaranteed".
  • Label every figure from the past as a past result ("past results don't predict future ones").
  • Use the app's exact names for pages, buttons and fields (Trading Center, Build Trade).
  • The text of an in-app info bubble and its docs page say the same thing.

Page template (an indicator or a feature)

# Name (Full name)

**What it shows / what it does:** one or two sentences.

**How people use it:** the common uses, in plain words.

## Settings

| Setting | Default | What it does |
|---|---|---|
| ... | ... | what moving it up or down changes |

## Ready-made conditions (indicators only)

## Warnings you may see

- **The warning, as the app shows it**: what it means and what to do.

## Good to know

"For the docs" in pull requests

Every PR that changes something a user can see fills in the For the docs section of the PR template, so the docs can follow:

  • What the user sees: the new or changed page, field, button or message.
  • What each setting does: in plain words, as the info bubble says it.
  • Defaults: each setting's default, or "no default (required)".
  • Warnings: the exact text of any new warning or error, and when it shows.

Write "None" when nothing user-visible changed.