Documentation: Chapter

Read in 2 minutes ·

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:

  1. An overview of the architecture and services used;
  2. How it interacts with other parts of the app;
  3. A description of critical operations;
  4. Testing considerations;
  5. FAQ with common questions;
  6. 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?”

If you like this post, follow me on Twitter or Telegram