Onboarding
Onboard people into what the product does.
A new engineer, tester, support agent or product manager needs the same thing on day one: an accurate account of what the product does, including the cases that surprise people. Most teams hand them a wiki, some tickets and a Slack invitation. A current specification gives them the product itself, in plain language.
What new people are really asking
Whatever the role, the first weeks are a stream of questions about the product. What does it do? What happens when a customer does this unusual thing? Why does it work that way? Where is that checked?
- An engineer wants to know what else a change will affect before making it.
- A tester wants to know what the product should do, so they know what to check.
- A support agent wants to know what is supposed to happen when a customer reports something odd.
- A salesperson or a customer success manager wants to know what the product can honestly be promised to do.
The edge cases are the hard part
The main path of a feature is easy to explain and easy to find in a wiki. The edge cases are where new people get stuck, because that knowledge is rarely written down. A discount code that expires at the end of the day it names, in the store’s time zone. A refund after a partial shipment. A user who is removed from a team while holding the only copy of a document. These cases are in the code, in old Slack threads and in the memory of whoever fixed the bug.
Onboarding then becomes a series of interruptions. Each answer costs a senior person some time, and each one is given from memory.
A specification that records them
SpecTrail derives the specification from the code, so the behaviour that exists in the product is what gets described. Each requirement has acceptance criteria written in plain language, and the edge cases are among them. A new person can read down from an epic to a feature to a requirement and see how the product behaves, in the words the team uses.
The small marks beside each statement show the code behind it and the tests that cover it. For an engineer, that is the path from the behaviour to the file. For a tester, it is a view of which behaviours have checks and which do not.
Ask, instead of searching
The specification has a question bar for asking or jumping to anything. A newcomer can type the question they would otherwise put to a colleague, and it finds the requirement that answers it and shows where in the document it came from. The answer comes with its source, so people learn where to look as well as what the product does.
A first-week path
- Read the epic and feature names, to get the shape of the product.
- Read the requirements of the three features you will work on, edge cases included.
- Look at the marks to see which of those behaviours have tests and which do not.
- Read the recent history to see which requirements changed lately, and why.
- Ask questions in the question bar, and note anything the specification does not answer.
Anything the document does not answer is a useful discovery too. It marks a behaviour that the code has and nobody has described, which a person can review and add.
The document stays true
An onboarding wiki is accurate on the day it is written. A specification that follows the code stays accurate as the product changes, because each merged change is compared with it and the ones that alter behaviour are decided on and recorded. The newcomer who joins next year reads the same document, in its current state, and the history shows how each requirement got there.
Related: inherited codebases · how a small startup keeps track of its product · what to test first when you have no QA team