Skip to main content

This is a new service – your feedback (opens in a new tab) will help us to improve it.

SEGAS-00003 Minimal documentation set for a product

Last updated: 14 March 2024
Relates to (tags): Documentation, Ways of working

A product should be documented to a minimum standard so that new engineers can be easily onboarded, and knowledge is not siloed within the team.


Requirements

Product documentation MUST include a description of the product and what it is for

The description should provide domain context to an engineer and link to product documentation, including:

  • Information about the team
  • Key stakeholders
    • Include contacts in case of a technical incident with the product
  • Who the Senior Responsible Owner (SRO) is
  • User research findings
  • Product roadmap
  • Business analysis findings
  • Governance and assurance documentation
    • IT health check reports
    • Security audits
    • Service design package which MUST include the incident management process

Product documentation MUST include key architectural views

The architectural views may contain architecture diagrams, security models, entity-relationship models. The views should allow an engineer to understand how the components interact at a high and low level.

Product documentation MUST include a decision log

A decision log should record key design decisions in context. A pattern should be selected to complement the team ways of working, and may include for example Architecture Decision Records.

Product documentation MUST include runbooks for expected tasks

Document any incident support, disaster recovery, and maintenance tasks that are the responsibility of the product team.

Where a task can’t be automated, provide a runbook detailing how to carry out that task.

Product documentation MUST include information about observability

Documentation should include details of logging, alerting and monitoring designs, and links to alerting and monitoring dashboards.

Product documentation MUST include build, release and deployment processes

Documentation should enable an engineer to create builds, find artefacts, package releases, deploy services, and manage environments.


Content version permalink (GitHub) (opens in a new tab)