Knowledge base
Admin, Knowledge base (/admin/kb). Needs module.knowledgeBase and the
kb.manage permission.
Write articles, organise them by category, publish them. Published articles
appear on the public help centre at /help.
What to write
Section titled “What to write”The ten questions your desk answers every week. Not a manual.
A test: have you sent the same canned response more than about ten times? If so, that answer belongs somewhere nobody has to ask for it.
A reasonable starting set for a school:
- How to connect to the school Wi-Fi
- How to reset your password
- How to book a repair
- What to do if your device will not charge
- How to print from a personal laptop
- What a loan device is and what to do with it
- How to install the software you are expected to have
Seven articles covering most of your volume beats seventy covering everything.
Writing them
Section titled “Writing them”Title them as the question somebody asks. “How do I connect to the Wi-Fi” is findable by search. “Network access configuration” is not, because nobody types that.
Write for the person asking. “Settings, Wi-Fi, pick SCHOOL-WIFI, enter your school password” beats a description of 802.1X.
Include the thing that always goes wrong. Most articles exist because a step confuses people. Say so, rather than assuming the happy path.
Keep it short. An article that fits on a phone screen gets read.
Say when it was last checked. An article describing last year’s Wi-Fi setup is worse than no article, because people follow it.
Categories
Section titled “Categories”A flat set of categories, used for grouping on the help centre.
Keep the list short. Search is how people actually find things, so categories are for browsing rather than for taxonomy. Five or six is plenty.
Draft and published
Section titled “Draft and published”Drafts do not appear publicly. Publish when it is ready.
Worth writing drafts as you go rather than in a block. The best time to write an article is immediately after answering the question for the third time, while you still remember what confused them.
Reviewing
Section titled “Reviewing”Put a termly reminder in the calendar to read the lot. It takes twenty minutes and it catches the article describing a system you replaced in April.
The articles that go stale fastest are Wi-Fi, printing and anything naming a version number.
Where they appear
Section titled “Where they appear”The help centre at /help, publicly, with full-text
search.
The kiosk links to it under “Help and guides”.
Permissions
Section titled “Permissions”| Permission | Allows |
|---|---|
kb.manage | Write, edit and publish articles |
Reading is public and needs no permission at all.