Skip to main content

​
Before you start

  • The mint command installed (npm i -g mint) so you can preview and validate.
  • The git hook wired once per clone: git config core.hooksPath scripts/githooks.
  • A clear answer to “is this page an explanation, a how-to, or a reference?” If you cannot answer, it is two pages.

​
Steps

1

Copy a template

Copy the matching file from templates/ into the right folder. The folders mirror the menu: handbook/, systems/, reference/.
2

Fill the front matter

Every page needs title, description, and kind (explanation, how-to, reference, or hub). A page goes in only when it is finished; there are no placeholder pages.
3

Check every fact against the code

A timing, a threshold, a name, a trigger: find the code, the config row, or the vendor setting that makes it true before you write it. Put the proof in the commit message, not on the page.
4

Write it like you would say it

Short sentences. “You”, not “the user”. Say customer and work order, never the code names. If you must show a code name, it goes on the Names page, nowhere else. Say what is true today. No dates, no promises about later, no ticket ids, no notes about how it was tested.
5

End with Related

Every page ends with a ## Related list of at least one link: the explanation page for its chapter, the system pages it touches, or the reference tables it leans on.
6

Put it in the menu

Add the path to docs.json under the right tab and group. A page not in the menu fails the check.
7

Run the check

It reads every page. It fails on a missing title or kind, a page not in the menu, a broken link, a code name outside the Names page, a robotic phrase, a Title Case Heading, a date, a ticket id or a test note, or anything that looks like a secret.

​
How you know it worked

scripts/check.sh prints ok, and mint dev shows the page in the menu where you expect it.

​
When a page changes

When the system changes, the page changes in the same change or the same sitting. A page that describes what the system used to do is worse than no page.