Skip to main content

Documentation

This page was last reviewed 6th March 2024. It needs to be reviewed again on the 6th December 2024.

What is the standard for documentation?​

Include documentation in your project that facilitates understanding, usage, and maintenance of your code. The documentation should promote usability and longevity of your project, and effective collaboration among your stakeholders.

When and for whom is this standard applicable?​

This standard applies to front-end and back-end developers.
This standard must be applied to all new repositories of the city of Amsterdam (new since May 2024).

What is required to document?​

Project documentation must include the following:

  • the main idea of the application
  • the license EU-PL v1.2
  • a ReadMe (please follow the guidelines on what to include in a ReadMe [ToDO: reference to where documentation about ReadMes will be])
  • all architectural decisions made, use the format Architecture Decision Record (ADR)
  • a changelog and a future review date
  • information about what data is processed by the application
  • API documentation (endpoints, parameters, request/response formats and examples, authentication requirements)
  • list of features of the application, including the purpose of each feature

What to avoid?​

Documentation is not a one-time task. Regularly review and update documentation to ensure accuracy and relevance over time.

Considerations​

  • Decide the target audience. Tailor the documentation accordingly, providing explanations that are appropriate for the intended audience.

Further reading​

  • The blog post about Architecture Decision Records by Michael Nygard.

Acknowledgements​

Many thanks to Hee Chan van der Haar and Sirée Koolen-Wijkstra