Skip to content

Documentation and Handover ​

Another team, or an AI agent, must be able to run, change, and support the software without the original author.

Requirements ​

  • README in every repository: what the software does, how to run it locally, how to deploy it, and who owns it.
  • Configuration list naming every environment variable and secret the software needs (names only, never values).
  • API documentation for every interface another system uses, kept in step with the code and versioned.
  • Release notes for each production release, written in plain language for the people who use it.
  • Handover. At the end of a contract the team hands over the code, documentation, credentials (through the secrets store), build and deploy steps, and any agent instructions, so HCI can maintain the software with or without AI tools.

Recommendations ​

  • Keep architecture and workflow diagrams showing the components, the data each one stores, the contracts between them and how the main processes flow.
  • Write a short decision record for each significant choice, and for any departure from a recommendation.

Maintained by the HCI software department.