The project syllabus is a standardized, consistently-named reference document that captures a project's business context, people, personas, features, operational tasks, and tooling. Its purpose is continuity: the "why" and "how" of a project should survive when the people who built it move on. Tribal knowledge walks out the door eventually; the syllabus is what stays.

When to use this play#

Create a syllabus for any project expected to outlive its current team, which is most of them. The best time is at the start; the second-best time is now. Start from a template so every project's syllabus looks the same and a reader knows where to find things.

How to run it#

1. Anchor to three big questions. Every project answers, up front:

• What is the business benefit?
• How does it relate to the broader strategy?
• How will success be measured?

If these are not written down, the project's purpose lives only in conversations that will eventually stop happening.

2. Capture WHO. Document current and past stakeholders and contributors along with their roles. Past contributors matter because they are who a future engineer will wish they could ask.

3. Document personas and major features. For each feature, record:

• Which personas get value from it, and what value.
• Integrations and dependencies.
• Key business rules.

The business rules are the part most likely to be undocumented and most expensive to rediscover.

4. Document recurring manual maintenance tasks. Explicitly list the recurring manual tasks that keep the project alive: what the task is, when it happens, who to involve, and where the step-by-step documentation lives. These are the chores that nobody remembers until they break.

5. List the tooling and a directory of where everything lives. Record the DevOps and tooling stack, and a directory pointing to repositories, the wiki, tickets, the shared drive, chat, and the secrets manager. A new engineer should be able to find everything from this one page.

6. Store it somewhere known, named consistently. Put it in a predictable location with a consistent name. A syllabus nobody can find is no better than no syllabus.

The companion README standard#

The syllabus describes the project; each repository's root README describes that repository. Every README should cover enough that a new engineer can run the code without tribal knowledge:

• Purpose: what this repository is and does.
• Tech stack: with versions.
• Local setup: how to get it running on a fresh machine.
• Testing: how to run the suites.
• Deployment: how it ships.

Common traps#

• Documenting the what but not the why. Without the business benefit and rules, the next team can read the code and still not know what they are allowed to change.
• Forgetting past contributors. They are often the only source for decisions made years ago.
• Leaving manual tasks undocumented. Recurring chores are exactly the knowledge that vanishes with turnover.
• Inconsistent naming and storage. If each project files its syllabus differently, nobody trusts that one exists.

Signals it's working#

• A new engineer onboards from the syllabus and READMEs rather than from a series of meetings.
• When someone leaves, the project keeps running because their knowledge was written down.
• People reach for the syllabus to answer "why does it work this way" instead of guessing.

How it ends#

A syllabus is never truly finished; it is maintained. Treat updating it as part of the work, the same way you treat instrumentation as part of "done." Its value is measured the day a key person leaves and the project does not skip a beat.