Documentation

/docs. Needs module.docs.

The writing your technicians work from: runbooks, procedures, comms room notes, the things a school currently keeps in a shared drive, a Confluence nobody renewed, or one person’s head.

Every page here is behind a sign-in. Nothing in this module is ever served publicly. That is the knowledge base’s job, and the difference between the two is the last section on this page.

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

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.

Two details are worth knowing because they are easy to assume the other way:

A title is content. Restricted documents are excluded from search results, ticket suggestions and the assistant 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

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, which is what makes a history readable six months later.

A named owner

Each document can carry an owner. This is not decoration: an unowned document is one nobody has agreed to keep true, and those are the pages that quietly become wrong.

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

A document can carry a review cycle in months, up to twenty-four. Past two years a school is saying the page never expires, and leaving the cycle empty already says that honestly.

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

The part that makes this more than a wiki.

A wiki answers “where is it written down”. A service desk can answer a better question, “what is written down about the thing in front of me”, because it already knows what the thing in front of you is.

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 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 named service, then the device model, the asset type, the ticket category, and the campus last. A document bound only to a campus is real but weak, and must never outrank 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. Where a person has been explicit, the guess does not get to argue.

Search

Searching reads the whole document, not its title, ranks the results, and shows the sentence that matched.

That matters for the runbook whose title is “Start of year” and whose one useful line is on page three. It also means a suggestion can be dismissed without opening it, which is the difference between a search box people use and one they stop trusting.

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

A live document can be copied onto the school’s public help centre as a knowledge base article. This needs docs.manage. Writing a runbook and deciding the internet may read it are different decisions, and only the second is irreversible in the way that matters.

Four things about it:

• 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. A copy that outlives its source is worse than no copy.

Against the knowledge base

They are two products that look similar and are not.

	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, from Standard	module.knowledgeBase, Core
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.

Most schools want both. 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

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