Skip to content

Home / 🟠 AREAS / Knowledge Management / Playbook template

Playbook template

Every page of the playbook has the same shape: a breadcrumb line, a title, a TL;DR, and the sections below, in this order.

The playbook is written in Markdown in the repository ABITELLO-playbook and published with MkDocs.

The shape of an area page

  1. Breadcrumb line — the first line of the file: [Home](index.md) / [🟠 AREAS](areas.md) / **Finance**. It is for reading the file in a Markdown editor and is hidden on the website. It links only to pages in docs/.
  2. Title (H1) — the area's name.
  3. TL;DR — one or two sentences: what this area is for, as <div class="tldr">…</div> directly under the title.
  4. Purpose — what the area covers and where it ends, in one to three sentences.
  5. Processes — each workflow as a short numbered procedure: trigger, steps, result. A workflow longer than a screen gets a sub-page of its own.
  6. Rules — what always applies in this area.
  7. Where things live — repositories, folders, systems.

An area page with sub-pages stays an overview: it explains the purpose and links each sub-page in a sentence that says why to open it.

Rules for every page

  • A page describes what is valid now, as a binding instruction. No «provisional», «planned», «for now».
  • One fact, one home. Link to the source instead of copying it.
  • Every Markdown list is preceded by a blank line, or MkDocs renders it as plain text.
  • Images carry an explicit width: ![Name](images/name.png){ width="400" }.
  • No secret, no password, no private network address.
  • A new page goes into both navigation files in the same step: nav in mkdocs.yml, and NAVIGATION.md.
  • File names are lower case, the area first: finance_accounts-payable.md.
  • English (UK).

Boxes

For a warning or an important special case in the middle of a page, use an admonition; the text is indented by four spaces:

!!! warning "Title of the note"

    Text of the note — short.

note, info and tip are light blue, like the TL;DR box; warning, danger and important are light orange, for the few things that must not be missed. A diagram or an image opens large when it is clicked.

This is a note

It looks like this.