This is part 3 of 3 about feature documentation on feature-based teams.
Part 1 - The problem
Part 2 - Squad level documentation
Part 3 - Chapter level documentation
All platforms are different and deal with different limitations/constraints so it is considerably harder to create a template that would work for all platforms. However, one question that we should always have in mind is:
”What would a colleague of mine need to know if he/she started to work alongside me in a shared codebase?”
This helps us envision the use case in which a document would be useful:
As an iOS developer, when I join a new squad, I want to have a high-level idea of how my iOS colleagues have implemented the feature and how all the components interact with each other.
For this scenario, I have come up with a template (see here) that would work well for most features, independently of the feature that we implement:
- An overview of the architecture and services used;
- How it interacts with other parts of the app;
- A description of critical operations;
- Testing considerations;
- FAQ with common questions;
- References to documents and pages specific to the platform.
Finally, I would advise you to avoid any code snippets (use pseudo-code instead) and as fewer implementation details as possible, as these should live closer to the code in the pull requests description.
Once you finish writing the document, I would recommend you to request a review from your peers and improve it until they answer affirmatively to the following question:
”If I just started working on this feature and I looked at this document, is the content here enough for me to start without having to reach out to the original developers?”