Milestone map
Milestone map
3 milestones
Write a tested technical onboarding document for a real codebase
3 weeks
Choose a real open-source repository or your own project and write a technical onboarding document for a new engineer joining the project. Cover: what the system does (one-paragraph business context), how to set up the development environment from scratch (tested commands), repository structure (what each directory is for), how to run the tests and what the test suite covers, and how to deploy to staging. Every command must actually work — test them on a clean machine or container.
Proof required
Onboarding document (600+ words) covering business context, verified setup instructions, repository structure explanation, test suite documentation, and deployment steps — plus a note confirming the setup instructions were tested on a clean environment.
What gets checked
- Every shell command was executed on a clean environment and produced the expected output — no assumed steps
- Repository structure section explains purpose (why each directory exists), not just lists names
- Testing section explains what the test suite covers and what it does not
Common mistakes
- Writing from memory rather than testing commands on a clean environment — instructions that work for the author often fail for a reader starting from zero
- Explaining what components are called without explaining what they do or why they exist — structure maps help navigation, not understanding
- Skipping the deployment section because 'it's complex' — deployment documentation is where new engineers most often get stuck
Resources
Foundationstart here
What a verifier looks for
- Ask the candidate to demonstrate one setup step from the document — confirm it produces the expected output
- Review the repository structure section — confirm it explains purpose, not just lists names
- Check the testing section — confirm it explains what is covered and what is not
Write an API reference and a conceptual architecture document
4 weeks
Write two different types of technical documentation: (1) an API reference for a real API covering authentication, endpoints or methods, request/response formats with working examples, error codes with recovery guidance, and rate limits; (2) a conceptual architecture document for the same or a related system explaining how major components interact, why the architectural decisions were made (not just what they are), and what trade-offs were accepted.
Proof required
Two documents: (1) API reference covering authentication, endpoints or methods, working request/response examples, error codes with recovery guidance, and rate limits; (2) architecture document explaining component interactions, decision rationale, and accepted trade-offs.
What gets checked
- API reference includes at least one working code example per endpoint or method
- Architecture document explains WHY decisions were made — not just describes the architecture
- Error codes include recovery guidance telling the developer what action to take, not just what went wrong
Common mistakes
- Writing an API reference that describes what the API does without showing how to use it — a developer should be able to copy-paste a code example and make a successful call immediately
- Writing an architecture document that is a diagram caption — a diagram with no rationale for design decisions is not architecture documentation
- Error code documentation that only describes the error without guiding recovery — documentation without actionable steps is not useful
Resources
Foundationstart here
What a verifier looks for
- Test one code example from the API reference — confirm it runs without modification
- Review the architecture document — confirm it explains decision rationale, not just diagram labels
- Check error code documentation — confirm at least two codes include recovery guidance
Publish documentation and collect engineer feedback
3 weeks
Publish or submit at least two of the documents from M1 and M2 to a public or semi-public audience — options include a README contribution to an open-source project, a post on Dev.to or a personal technical blog, or an internal documentation system where engineers use it. Collect feedback from at least two engineers who used the documentation to complete a task. Document their feedback and at least one change made based on it.
Proof required
Links to the published documentation (or screenshot if internal), plus documented feedback from at least two engineers who used the documentation to complete a task — including one specific change made based on their feedback.
What gets checked
- Documentation is published and accessible to engineers outside the author — not draft or private
- Feedback comes from engineers who used the documentation to do something — not from people who just read it
- At least one concrete change was made to the documentation based on reader feedback
Common mistakes
- Asking for feedback from people who will validate rather than use the documentation — feedback must come from engineers who attempted to complete a task using the documentation
- Making no changes based on feedback — documentation that receives real use will always surface gaps; zero revisions signals the feedback was superficial
- Not recording what the readers did with the documentation — 'two engineers read it' is not the same as 'two engineers used it to set up the environment'
Resources
What a verifier looks for
- Access the published documentation — confirm it is publicly reachable or the screenshot is credible
- Review feedback documentation — confirm reviewers used it to complete a task
- Verify at least one specific change was made based on reader feedback