This help is a KB4IT knowledge base in the help/ folder of the repository, built with the apphelp theme.
help/
├── config/repo.json # apphelp settings and the Feature vocabulary
└── source/
├── index.md # the home page
├── getting-started.md # one file per page
└── resources/images/ # screenshots and the logo
Write for the reader
- Start from what the reader wants to do, not from how the code is organised.
- One page, one goal. Give it a
DocType: a tutorial teaches, a how-to guide solves one problem, a reference lists facts, an explanation gives the why. - Short sentences and plain words. Show the command, then what it prints.
- Check every command and every claim against the code before you publish it.
Add a page
- Copy a page of the same type and rename it:
howto-…,reference-…,explanation-…,dev-…. - Set its properties:
DocType,Section,Order,Summary,Featureand, if useful,HelpId,KeywordandRelated. - Add it to the home page in
index.mdif readers should find it there.
Feature and Level values must be in the vocabulary of help/config/repo.json; add a value there before you use it.
Check it
kb4it verify help/config/repo.json
kb4it build help/config/repo.json
xdg-open help/target/index.html
The help is strict: a missing property, an unknown value or a help id that points nowhere stops the build. Broken links are reported as warnings; fix them too.
Screenshots
Keep them in help/source/resources/images/ as WebP, 1280 pixels wide or less. Use sample data, never real names or paths from your computer.
Publish
.github/workflows/help.yml builds the help with the KB4IT of the same commit on every push that touches help/ or the code, and publishes it to GitHub Pages from master. On other branches it only builds, so a broken page fails the pull request instead of the site.