In-repo technical documentation

Product Docs

This site represents an example of how to structure documentation for display using mkdocs.

Usage

How do I add documentation to product?

  1. Start a new mkdocs project under the top-level product repo.
  2. Copy the product template and the scripts folder in this example doc into the product repo.
  3. Configure the mkdocs.yml file as appropriate for your product.
  4. Configure the scripts and hosting for the generated documentation.

Note: this only has to be done once per product. A product may be one or more repositories, but we’re only expecting one set of docs per product.

How do I update documentation already in this form?

  1. Edit it as you would any other code!
  2. The generation of the HTML form is either manual or automatic, but refer to the product documentation for details on that.

Rules of the system

  1. One product may contain one or more git repositories. It’s expected that all repositories relating to that product are kept in the same location (eg locally, github, bitbucket, gitlab, etc).
  • Good: All repositories for product A are kept on bitbucket.
  • Bad: Product B has repositories locally, on github and gitlab.
  1. Each git repository is identified by a readme.md file containing, at least, it’s Product/Component/Subsystem reference.
  2. The top-level subsystem repos contain a subsystem.md file.
  3. The top-level component repos contain a component.md file.
  4. The top-level product repos contain a product.md file and the necessary scripts to generate the product documentation.

Principles

System Componentisation

Having a componentised product (not necessarily a modular one) means turning a large product into several smaller products.

Using smaller components offers the following benefits:

  1. Learning the system: constraining the amount of information and context you need to hold in your head as an engineer when reasoning about the system makes learning and training easier.
  2. Separation of concerns: keeping the components independent makes testing and replacing parts of the system easier.
  3. Individual autonomy: the cost of communication goes up as the amount of people who need to be consulted increase. Giving complete ownership to a dedicated group of people allow them to rapidly iterate on changes to their component, because they are empowered to do so.
  4. Customer-focused: slicing the components by customer benefit, and orienting groups of people around that customer benefit offer the opportunity for a much deeper relationship with the component, since you get to know your customers that much better.

Product Area Ownership

If everyone owns everything, then no one owns anything. This means in a large product, everyone must also understand everything in order to change anything.

Product area ownership is the system that governs the rules surrounding the components, just as the agile process offers rules and guidelines around getting work done.

Product Area Ownership Policy

  • Every repository under a product must be part of a subsystem or component.

  • All repositories under a product contain a reference to the subsystem or component that they belong to (a readme.md if the repo is just “there”, or a component.md or subsystem.md for top-level repositories.)

  • Each component has a named, designated owner.

  • When working under the PAO policy, you need to check if the repo you are proposing to change is yours or someone else’s before making changes. The quickest way is checking the root directory for a component.md or subsystem.md file, or failing that, looking at the readme.md.

  • Owners have the following rights and responsibilities:

    • To petition/plead/bribe the PO for making changes to their product area.
    • To have the final say on any technical changes in their area (Principle Engineers are able to veto this if absolutely necessary)
    • To run all the tests pertaining to their area, to prove the quality to their own satisfaction.
    • To generate metrics to demonstrate improvement or degradation of their area.
    • To enable other teams access to their components via known, documented, and discoverable APIs.