Write a Handbook Section

You write the page an employee reads to find out how something works here, and you make it the one place they need to look. A handbook explains; a policy binds. Your section tells people what to do, in what order, with examples, and links to the policy where the rules are formal. The standard: a new hire finds the answer in under a minute, the page is accurate for every country the company employs people in, and someone owns keeping it current.

When to use

• "Write the handbook page on expenses."
• "New hires keep asking how holiday works, put it in the handbook."
• "Our remote working page is from before we went hybrid, rewrite it."
• "Start a handbook for us, we don't have one."

What you need

• The topic, and the actual current practice (which is often different from what is written). Ask the person who runs it with ask_teammate.
• Any existing policy, contract terms or old handbook text on the topic (search_files, read_file).
• The countries and, where relevant, states the company employs people in.
• The company's tone of voice, if documented, and where the handbook lives (wiki, document store, intranet).
• Access: the handbook location through a connected app (for example a docs or wiki tool) or the agent's own browser signed in by the owner. You draft; publishing is the owner's decision. Without access, deliver the section as a Markdown file.

Method

1. Find the real questions. Collect the questions people actually ask about the topic: search chat history the owner allows you to see, ask HR and managers, and look at the new-hire survey.
   • List the top 5 to 10.
   • The section must answer all of them.
2. Establish the facts. For each question, get the current answer from the person who owns the process.
   • Where the answer depends on the law (holiday minimums, parental leave, sick pay, working time, expenses tax treatment), research the rule for each country with web_search on official government sources, and record the source and date.
   • Mark every such statement "[to confirm with a qualified HR professional or employment lawyer]" until someone with that standing has checked it.
3. Decide what is handbook and what is policy. If the content creates rights or obligations (who is entitled to what, what is a breach), it belongs in a policy; the handbook summarises it in plain words and links to it.
   • Do not create contractual promises by accident: words like "guaranteed", "always" and "will never" can be read as commitments.
   • In some countries handbook content can become part of the contract; check, and use the disclaimer the owner's adviser approves.
4. Structure for scanning. Use the template in references/section-template.md: a two-line summary at the top, "how to" steps numbered in the order people do them, a short "who it applies to", worked examples, FAQs from step 1, where to get help, the linked policy, and the owner and review date.
5. Write plainly. Second person ("you can carry over up to 5 days").
   • Sentences mostly under 20 words.
   • One idea per paragraph.
   • Define a term the first time you use it.
   • Use the names of real tools and real people's roles ("ask your manager in the HR system"), not abstractions ("submit via the appropriate channel").
   • Aim for a reading level a 14-year-old could follow; check with a readability formula in execute_code if useful (Flesch Reading Ease above about 60 is a reasonable target for this kind of text).
6. Make it fair and inclusive. Use gender-neutral language.
   • Cover the different situations people are in: part-time, shift workers, remote, other countries, people with disabilities, carers.
   • If a rule differs by country, show a small table rather than burying it in prose.
7. Review. Send the draft to the process owner for accuracy and to the owner for approval.
   • Legal statements go to a qualified reviewer.
   • Note who approved what.
8. Publish and announce (with approval). When approved, publish where the owner says and draft a two-line announcement for the team. Set a cronjob reminder for the review date (12 months by default, or sooner for anything tied to law that changes often).

Judgement calls

• Practice and written policy disagree: do not pick one. Show the owner both and ask which is right, then fix the page and either the policy or the practice.
• Sensitive topics (sickness, family leave, harassment reporting, money troubles): take extra care with tone, and put the route to a human near the top.
• A rule differs for a handful of staff in one country: still show it. A short table row is fine; silence is not.
• The owner asks you to leave out a legal entitlement so fewer people use it: do not. Flag it and explain the risk.
• An old page with no owner: propose one rather than leaving the field blank.
• A question nobody can answer: write "we are deciding this; ask " and tell the owner, rather than inventing a rule.

Output

• handbook/<topic>.md: the section, using the template.
• A sources note: each factual or legal statement, its source URL and date, and its review status.
• A draft announcement for the owner.

Sources note layout:

| Statement on the page | Applies to | Source (official) | Checked on | Review status |
| "You get 28 days including bank holidays" | UK staff, full-time | <gov URL> | <date> | to confirm with <qualified reviewer> |

Checks before you finish

• Every link, tool name and form on the page works and is current.
• The page reads correctly for part-time, remote and overseas staff, not just the head office.
• Every top question from step 1 has a clear answer on the page.
• Every legal statement has a source and is marked reviewed or "to confirm".
• Nothing reads as an accidental contractual promise.
• Country differences are shown explicitly.
• The page names an owner and a review date.
• Nothing has been published without the owner's approval.

Pitfalls

• Writing the ideal, not the real. If the page says one thing and managers do another, people trust neither. Write the real practice, or get the practice changed first.
• Legalese. "Employees shall be entitled to..." helps no one. Put formal wording in the policy and plain steps in the handbook.
• One country's law for everyone. A UK holiday rule is wrong for staff in Germany or Texas. Check each place you employ people.
• No owner. Pages without an owner rot within a year.
• Duplicating the policy. If the handbook restates numbers from the policy, they drift apart. Quote the key number once, link the policy, and update both together.
• Burying the answer. If people must read five paragraphs to find out how to book a day off, they will message HR instead. Put the steps first.

See also: draft-hr-policy for binding rules, and onboarding-plan for choosing which pages a new hire reads first.