Writing for the Handbook – Engineering Handbook

This page is the contract for anything published on this handbook. It is written to be read by two audiences at once: engineers writing or editing a page, and AI agents doing the same. Both should be able to decide, without asking anyone, whether a page belongs here, what kind of page it is, and where it goes.

Read it before you create a page.

1. What this site is #

This handbook is the portal for how we do engineering at Human Made. It is public, deliberately.

It contains our engineering rules, the procedures we follow, and the reasoning behind both. It does not contain the following.

Not this	Where it goes
Agency operations, delivery process, sprint ritual	The Human Made Playbook
HR, careers, progression, reporting lines, org structure	The company Handbook
Company values and behaviour framework	The company Handbook — link to it, never restate it
Anything client-confidential or project-specific	The project’s own repository or wiki
Credentials, environment URLs, access details	1Password

The site is public. Treat every page as though a prospective client and a prospective hire will both read it, because they will. If a sentence would need removing before you showed it to either, it does not belong here.

When something is nearly in scope, ask whose question it answers. If the reader wants to know how Human Made runs engagements, it is the Playbook. If they want to know how they, an engineer, do this well, it is here. Offboarding is the useful test case: the commercial shape of ending an engagement belongs to the Playbook, and the engineering handover belongs here.

2. The four kinds of page #

Every page is exactly one kind. The kind governs how you write, not how the reader browses — it never appears in the navigation.

Kind	The reader’s question	You are writing	Lives in
Standard	“What is the rule?”	A rule they can look up and comply with	Standards
Guide	“How do I do this?”	A procedure that gets one job done	Guides
Background	“Why do we do it this way?”	The reasoning behind a rule or a choice	How We Work
Walkthrough	“Teach me this from scratch”	A lesson, in order, for someone new	Reserved — see section 6

Choosing the kind #

Ask what the reader has in their hands.

They are mid-task and need to check something → Standard.
They have a job to finish and do not know the steps → Guide.
They are deciding, or disagreeing with a rule → Background.
They are new and do not yet know what they do not know → Walkthrough.

If two of those are true, you have two pages. Write both and link them to each other. Do not write one page that does both — that is the most common defect on this site, and it is why readers cannot always tell a rule from a suggestion.

What each kind must never contain #

A Standard must not contain step-by-step procedures, rationale essays, or anything that varies by project or tool version. State the rule; link to the Guide for the steps and the Background for the reasoning.

A Guide must not contain rules — link to the Standard. It must not contain philosophy — link to the Background. It must never contain credentials or environment access of any kind.

A Background must not contain rules, procedures, tool versions, or anything about people, roles or careers.

3. Page anatomy #

Every page opens with a lede — one or two sentences, before any heading, saying what the page covers and who it is for. A page that opens directly on a subheading is broken. The lede is what tells a reader arriving from a search engine whether they are in the right place.

A Standard #

Lede: what this governs, and where it applies.
The rules, as scannable statements. Use MUST for non-negotiable, SHOULD for a strong default with legitimate exceptions, and MAY for permitted. Use them literally and sparingly.
Exceptions, if any, and who can grant them.
See also — the Guide that implements it, and the Background that justifies it.

A Guide #

Lede: what you will have when you finish, and what you need before you start.
Numbered steps, one goal per page. If it forks into “or, if you are on VIP…”, that is two guides.
How to check it worked.
See also — the Standard it complies with.

A Background #

Lede: the question this answers.
Prose. The trade-off, the alternatives we rejected, and why.
See also — the Standards that follow from it.

4. Titles and naming #

Standards are named for the thing they govern: PHP, Security, Privacy, File Structure. Nouns.
Guides are named for the job: Releasing a plugin, Reviewing a pull request, Setting up your environment. Verb-first where it reads naturally.
Backgrounds are named for the idea: Built to Last, Modularity, Complete Software.
Never reuse a title. If two pages want the same name, one of them is in the wrong place, or they are the same page.
Never title a page “Best Practices”. It describes every page here and distinguishes none of them. Name the subject.
Beware the ambiguous noun. “AI best practices” means both “how we use AI to build things” and “how we build AI features” — two different pages in two different sections. Name which one you mean.

British English. Second person. Present tense. Say “you”, not “the developer”.

5. Where a page goes #

Navigation is generated from the page hierarchy, so the parent you choose is the URL and is the menu position. Three rules.

The section is decided by the kind of page, per section 2. Not by its topic.
Standards are two levels deep at most — /standards/<thing>/. Do not add grouping levels inside Standards; the depth costs more than the tidiness is worth.
Guides and Backgrounds are three levels at most.

Cross-cutting topics do not get a section. A topic that spans all three kinds — AI, accessibility, security, performance, open source — gets a topic hub: a short curated page linking to the Standard, the Guides and the Background for that topic. A hub is the only place a topic is allowed to look like a section. Giving a topic its own top-level section puts every future page in two possible homes, which is how this site came to have three pages called Performance.

6. Walkthroughs #

There are currently none, and there is no section for them. If onboarding or learning-path material gets written, it earns a section at that point and not before. Do not file a walkthrough under Guides to get it published — a lesson in the Guides section is a Guide that does not work.

7. Keeping pages honest #

Every page has a named owner.
A page unchanged for three years is presumed wrong until someone confirms it. Roughly half this site is currently in that state.
Do not restate content that lives on another site. Link to it. Duplicated content between here and the company Handbook drifts out of sync within a year, every time.
Landing pages must say something. An auto-generated list of child pages is not a page — write two sentences about what the section is for, and check the list is still accurate.
Editing a live page stores a revision, so changes are revertible from the editor. Change only what is in scope; leave prose, block markup and link text alone unless the edit is about them.

8. For AI agents #

Follow sections 1 to 7. In addition:

Before creating a page #

Confirm it is in scope, per section 1. If it is agency operations, HR, or client-confidential, stop and say where it belongs instead.
Determine the kind, per section 2. If the requested page would be two kinds, propose two pages and ask which to write first. Do not silently write a hybrid.
Search existing titles for a collision, per section 4. Report it rather than creating a near-duplicate.
Set the parent per section 5. Do not create new navigation levels, and do not create a new top-level section without explicit human approval.

Before editing a page #

Fetch the raw stored content, not the rendered output. The theme wraps outbound links in href.li at render time; that wrapper is not in the stored content and must not be added to it.
Make targeted replacements on exact strings. Assert the expected replacement count, and that zero instances of the old string remain.
Re-fetch after writing and confirm the change.
Do not reformat, re-wrap or otherwise tidy content you were not asked to change.

Never write to a page #

Credentials, tokens, environment URLs, usernames, or password-manager references.
Client names or project specifics that are not already public.
Anything sourced from a private channel, ticket or document without a human confirming it is publishable.

Declaring the kind #

Set the page’s doc-type field to standard, guide or background. It is an editorial field: it does not render, and it has no public archive. Its purpose is the audit query — any page whose doc-type disagrees with the kind its section owns is a defect to be reported, not a judgement to be made.

When you are unsure, report the ambiguity with the specific options. Do not resolve it by writing something that is defensible under either reading.