Skip to main content

Readme files

This page was last reviewed on April 23rd, 2024. It needs to be reviewed again on January 23rd, 2025.

What is the standard for a README for the city of Amsterdam?​

There must be a README.md file for every Github repository of the city of Amsterdam. A README.md file should be an overview and list of instructions to help someone get started with your project.

When and for whom is this standard?​

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 must be included in the README?​

A README must include the following:

  • Name of the project and a short introduction. Give the objectives and motivation behind the project and, if applicable, give the URL of the web application.
  • Name of the team responsible for maintaining the project and how to contact them.
  • An installation guide which contains information about software dependencies.
  • A how-to build and test the application

What pitfalls to avoid?​

  • Not keeping the README up-to-date with the latest information about the project.
  • Providing vague or ambiguous installation instructions.

Considerations​

  • You should ask a member of your team to try the instructions and make sure they work.

Example​

An example can be found in the development-standards repository.

Acknowledgments​

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