Description of the product’s intent / proposition goes here. We also want to capture things such as:

  • Known limits
  • Markets
  • Persona

This top-level document doesn’t need to subsume every other document, but provide a launchpad from which other documents can be accessed. Since Product already capture persona information on Product Central, just link off from there.

This is the atlas-level map, where all continents and major countries are visible, and the laws of physics governing the world are spelled out.


Important words to do with this product. This might include references to words of equivalence, or terms that have been deprecated but are still in use.

Architecture & Design Principles

  • Technology
  • Coding styles
  • Design styles


Description of where one goes to get the source code for the product. A list of repositories if it’s relevant.


One or more list of:

  • what components are required for this one to function
  • what external or 3rd party services are used
  • what external or 3rd party software is needed
  • what libraries are used


Description of the process of creating the product. Include details around the build tooling, linking off to other product.mds if there is an involved build system to reference.

Test Tools

If there are test tools that are important at product level, list and provide details of them here.

Component list

A list of components that make up this product, and the reference to their file. A component is a technological division, rather than necessarily a user-facing module, although they are in most cases likely to be one and the same.


A list of owners of various areas around the product, this might include listing:

  • Product lead
  • Architecture lead
  • Process lead


A list and details of versions of the product, and any external references that are important to that particular version.

Other References

Anything else that we haven’t already got a list of goes here. This might include historic references to why this product exists, or cheat sheets on the language used. In most cases, I would expect this section to be empty.

Decision Log

A chronological list of decisions that have been made around the product, capturing key information and the context of the decision at the time. Useful for reference later on.

  • 20170411 Added a decision log. In a one-source-repo product, this is massive overkill, but once the product spans multiple repos, it’s important to capture the key decisions about the product in one single place. A great use for this would be to log a technology decision and include the key market drivers and customer information