Skip to main content

Readme files

This page was last reviewed on February 3rd, 2025. It needs to be reviewed again on November 3rd, 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 should briefly describe the project, its purpose, and provide clear instructions to help developers, contributors, and stakeholders navigate and use the repository effectively.

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. This should include:
    • A brief overview of the project’s purpose.
    • The main objectives and motivation behind it.
    • (If applicable) A link to the deployed web application and relevant documentation.
  • 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.
  • Guidelines on where to report bugs or request features (e.g., GitHub Issues, Jira).

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