How to write a management RoboWiki page

Why this page exists

The team has documented its technical work for years: code, designs, test results, build logs.

But we have not documented how the team is managed in the same way. Decisions about ownership, communication, and coordination have often lived in people’s heads. When those people leave, that knowledge leaves with them.

This page is a first step towards fixing that.

It explains how to write a management page: a page about a role, process, or decision, rather than a technical part of the rover. When you are documenting how the team works, rather than what it builds, use the structure below.

The one rule that matters

Write for the person who joins after you leave and has none of your context.

Imagine a new student who cannot ask you any questions and needs to understand the page in ten minutes.

That leads to two important rules.

State the rule, not just the example

Examples are useful because they show what something looks like. But a newcomer also needs to know exactly what they are expected to do.

A process page should include both:

• the example or template;
• the rule for using it.

For example: “Use this memo template, write the memo within 24 hours, and post it in #memos.”

Avoid “in my experience”

You are documenting how the team works, not giving your personal interpretation of it.

Write:

The team is structured as two wings.

Not:

In my experience, the team functions as two wings.

The page should still make sense after you are no longer here.

The shape of a good page

Every management page should answer three questions, in this order.

The order matters. It helps the reader understand the reason for the page before asking them to follow its rules.

1. Why does this exist?

Start with the problem the page is trying to solve, not the mechanics of the solution.

For example, the Memos page first explains that the GTM is not enough and that meeting minutes often go unread several folders deep. Only then does it explain what a memo is.

When people understand the problem, they are more likely to follow the process. A rule without a reason is much easier to ignore.

2. How does it work?

This is the main content of the page: the rules, structure, or steps.

Be specific. Use real channel names, deadlines, links, and responsibilities.

“Within 24 hours” is better than “promptly.”

“Post it in #memos” is better than “share it with the team.”

3. What does it look like?

End with something concrete that the reader can copy or refer to.

This could be:

• a completed example;
• a template;
• a diagram;
• one real case.

The Memos page ends with a full example memo. The Zulip page shows the channel structure.

Template

Copy this into a new page and fill it in.

[Page title]

Use a plain, searchable title such as “Memos,” rather than something like “Communication Protocol v2.”

Why this exists

Write two to four sentences explaining the problem this page solves and what tends to go wrong without it.

How it works

List the rules or steps.

Use bullets where helpful, and include real names, timeframes, channels, and links.

• [...]
• [...]
• [...]

What it looks like

Add a completed example, filled-in template, or diagram that the reader can copy.

Links

Add related pages, source documents, and links to any tools mentioned.

Writing a page about a role

Role pages need a slightly different structure because their purpose is to make ownership clear.

For each role, answer three questions.

Owns

What is the one thing this role is accountable for that no other role owns?

If two roles have the same answer, the boundary between them is unclear. In some cases, that may mean one of the roles should not exist.

Why this role exists

Describe a real failure that happened, or is likely to happen, when nobody clearly owns this work.

Be concrete.

For example, if External Affairs and PR both manage the same sponsor relationship without a single owner, a commitment may be made twice, or not made at all. That is the kind of failure that justifies assigning one clear owner.

Who fills it

State which person or existing position fills the role, and roughly how much of their time it requires.

Be honest about the trade-off. Time spent on this role is time that cannot be spent somewhere else.

The test for a role page

Ask whether you can name a real problem that occurred because nobody owned the work.

If you cannot, the responsibility may not need a separate role. It may be better placed within an existing one.

Checklist

Before publishing, check the following:

• Would a newcomer joining in September understand this without any other context?
• Does the page begin with why, rather than how?
• Is every rule specific, with real names, deadlines, channels, and links?
• Is there at least one worked example, template, or diagram?
• Have you removed anything that only makes sense to you, such as in-jokes, notes to yourself, or phrases like “in my experience”?
• Do all images render correctly?
• Do all links work?