Documentation
/docs. Needs module.docs.
The writing your technicians work from: runbooks, procedures, comms room notes.
Every page here is behind a sign-in. Nothing in this module is ever served publicly; that is the knowledge base’s job. The last section on this page compares the two.
Spaces
Section titled “Spaces”Documents live in spaces: a library per subject or per team, such as Comms rooms, Start of year, Printing.
A space carries a name, a key, a description and, optionally, a campus. A space pinned to a campus is “how things work at that building”, and a campus-scoped technician sees only their own.
Creating and configuring spaces needs docs.manage. Writing in one needs
docs.edit. Reading needs docs.view.
Restricted spaces
Section titled “Restricted spaces”A space can be marked restricted. Its documents are then withheld from
anybody who does not also hold docs.viewRestricted, a separate key granted on
top of docs.view, not instead of it.
Restricted is for the library that holds credentials a school could not rotate quickly: switch passwords, the after-hours numbers, how to get into the comms room. A technician who needs the printer runbook should not thereby be handed it.
A title is content. Restricted documents are excluded from search results, ticket suggestions and Ask entirely, never returned with their bodies withheld. “Compass admin password rotation” on its own says the credential exists, which system it belongs to, and that it is written down somewhere near this person.
The rule is applied when you ask, not when the document was saved. Whether somebody may read the space holding the switch passwords is a fact about them right now. A role removed this morning bites this afternoon.
Marking a space restricted re-stamps every document inside it, and takes down any help page article those documents had published outward. Unmarking it is a separate, audited decision, and the log says which direction it went and how many documents moved with it.
Version history
Section titled “Version history”Every save writes a version, from what is about to be replaced, in the same transaction. You can list a document’s versions and open any of them.
You can also give a save a note: why this change happened. The note lives on the version rather than on the document.
A named owner
Section titled “A named owner”Each document can carry an owner. An unowned document is one nobody has agreed to keep true.
When you inherit a school’s documentation, the fastest useful pass is to open the list, assign an owner to everything worth keeping, and archive the rest.
Review cycles
Section titled “Review cycles”A document can carry a review cycle in months, up to twenty-four. Leave the cycle empty for a page that never expires.
Once the cycle elapses the document is stale and says so. Review lists
everything past its date, and ?mine=1 narrows that to your own. Reading a page
and pressing Mark reviewed writes a version with no content change, so “somebody
checked this in March” is a fact the history carries.
A stale runbook is worse than a missing one, because a technician follows it.
Bindings
Section titled “Bindings”A document can be bound to:
| A device model | for Dell Latitude 3120 |
| An asset type | for Chromebooks |
| A ticket category | for Printing tickets |
| A campus | for this campus |
| A monitored service | about Intranet |
| A service | for Compass, on the service and on every ticket filed under it |
| A stock item | for USB-C adapter |
| A connector | The runbook for that integration |
| One ticket | Attached by hand to this ticket alone |
A ticket then shows the bound runbook before anybody searches, with the reason it is showing it. “Bound to Dell Latitude 3120” is something a technician can agree or disagree with; “shares four words with the subject” is not.
Bindings are tried most specific first: the ticket itself, then the service the ticket is filed under, then the monitored service it names, then the device model, a stock item, the asset type, the ticket category, and the campus last, so a document bound only to a campus never outranks the runbook for the exact printer somebody is standing in front of.
A binding always outranks word matching, and never by a margin a long document could close by repeating a word.
Known errors
Section titled “Known errors”A document bound to a problem reaches every ticket linked to it with Was caused by. It is listed first in the documentation on each of those incidents, ahead of every other binding, so a known-error write-up is in front of whoever picks up the next report. It is still subject to the same space restrictions as any other document.
The binding reaches the incidents whether or not the problem is marked a known error. The problem’s own Workaround field shows on each incident as well; the document is where the longer write-up lives.
To bind a document to a ticket in the editor, type the ticket’s number, such as
#123.
Search
Section titled “Search”Searching reads the whole document, not just its title, ranks the results, and shows the sentence that matched, so a suggestion can be dismissed without opening it.
Quoted phrases work, so does or, and so does a leading - to exclude.
Restricted documents are absent from the results entirely unless you hold
docs.viewRestricted.
Publishing outward
Section titled “Publishing outward”A live document can be copied onto the school’s public help
centre as a knowledge base article. This needs
docs.manage.
- One direction, one deliberate action. Never a checkbox that syncs on save. An internal runbook says “escalate to Craig on 0412…” and the public article says “raise a ticket”, and a school that finds the difference by reading its own help page has already published the phone number.
- A restricted document refuses to publish, whatever anybody clicks.
- The article lands unpublished. Turning it on is the knowledge base’s own decision, made on its own page.
- Replacing an article that is already live asks you to confirm, and there is a preview showing what the public reads now beside what it would read next.
Deleting the document, or restricting its library, takes the article down with it.
Against the knowledge base
Section titled “Against the knowledge base”| Documentation | Knowledge base | |
|---|---|---|
| Written for | Technicians | Students, staff and families |
| Who can read it | Signed-in staff, per space | Anyone who can reach the hostname |
| Module | module.docs | module.knowledgeBase |
| Permission | docs.* | kb.manage |
| Search reads | The whole body | Titles, summaries, bodies |
kb.manage is held by whoever maintains the school’s public help page. docs.*
reaches runbooks written for technicians, which is where the network layout, the
after-hours numbers and the “how to get into the comms room” instructions end up
whatever the policy says. That is why they are separate keys.
Once you have sent the same answer forty times, put it on the help page; keep the version with the escalation path in here.
Permissions
Section titled “Permissions”| Permission | Allows |
|---|---|
docs.view | Read documents and search them |
docs.edit | Write, update, delete, bind and mark reviewed |
docs.manage | Spaces, restriction, and publishing to the help page |
docs.viewRestricted | Read restricted spaces, on top of docs.view |