This document provides guidance on writing an effective README file for an open source project. It emphasizes that the README is the first introduction to a project and should explain what the project is, how it works, who the users are and its benefits. It recommends including the project name and description, comprehensive instructions for getting started, and information on how to contribute and ask questions. The document also provides tips for writing in a clear, simplified manner and lists examples of good README files.

1. Gemeente
Amsterdam
The README
The most important content in your project.

2. Boris van Hoytema
“Grow an Open Source ecosystem for cities”
boris@publiccode.net
@bvhme
Open Source Adviseur (extern)
Director
Consortium Open Source Development Manager
The Foundation
For Public Code
2

3. Shopfront for your project
The README is the first thing almost anyone sees and perhaps one of the critical
parts of the project. It serves as an advertisement for the product, indicator of for
what users it can be relevant, the primary user’s guide and the way to get new
collaborators up to speed.

4. Keep your users in mind
● Your teammates
● People new to your team
● (Potential) users of our projects
● Contributors, both in and external
● People interested in your work

5. 1. The project name and description

6. The README is an introduction. It should assume the reader
knows absolutely nothing about the software and should
provide a brief introduction. If software were a screenplay, the
README would be the elevator pitch. If a person finishes
reading the first 10 lines of frobnicator/README and still does
not know if frobnicator is a widget library, accounting software,
or a video game, then the author of the README has failed.
— William Pursell on StackOverflow

7. The description is a high-level overview of what the project is for, what it does and
in what way it should be used. The description can double as a mission to keep you
focussed and on track, so it is wise to define this as early in the process as possible.
Description

8. Be sure to answer these questions in your description:
● What is this project?
● How does it work?
● Who are the users?
● What is the benefit for the users?
● What is the goal of this project?
Answer these in the Description

9. Make it shine
Start with the most important things so people can continue their search if this
project is not what they are looking for.
Make this section shine: If your project has a front-end include a screenshot here; if
there is a demo or there are live examples, include links; if there are features, list
them.

10. 2. How to use what you’ve made

11. Comprehensive guide to get started
The basics a user needs to know to use the project. Be sure to document every
necessary step and some common edge cases to get started and point to relevant
further documentation if available.
These sections can be quite technical. You don’t need to explain everything as and
you can expect users to search the web for what they don’t understand.

12. We find it works really well if you follow a two-step approach to develop the content
for this section: first, help someone setup the site who has never done it before, and
then write down the exact instructions. Next, ask someone to follow those
instructions and see if you’ve missed anything.
— 18F: Making READMEs Readable

13. Keep it current
Make sure that these sections are always up-to-date. If you change functionality in
the code, update the README concurrently.

14. Simplify
Tip: If this section gets long and tedious it might be worth it to try and simplify the
process of getting started, as ease of use is one of the key reasons for developers
to use a project.

15. 3. How to contribute and ask questions

16. CONTRIBUTING
You should describe how to get involved in the project, contribute and ask
questions.
If you have a CONTRIBUTING file, be sure to point to it from your README.

17. You might need to explain more about
● Nomenclature: what words are used in the code and what do they mean
● Governance: how do contributions work and who makes decisions
● Architecture: what is the structure you’ve decided on, and what do
developers need to know about this
● Dependencies: what software does this project depend on
● Licence: what licence the project has and point to the LICENCE file.
Break long sections out into separate files.

18. ● Welcome message!
● Project description & vision
● Links to:
○ How to contribute & get
involved
○ License
○ Code of Conduct, reporting
info
A closer look at a README:
README example: STEMM Role Models App

19. HOW can we communicate better?
Image from xkcd, editor at http://splasho.com/upgoer5/
XKCD explained a complicated
subject using only the ten
hundred words people use the
most often
Jargon are terms with a
specific meaning in a given
field, obscure for people
outside that field. It can
exclude potential
contributors.

20. Let’s try this together.
http://splasho.com/upgoer5/
Try to explain your project using only the
ten hundred most used words
Breakout Rooms of 3-4, 10min

21. ● Purple Booth’s README Template
● Standard README - style specification
● PaperBadger - project README
● Thoughtbot’s Blog on How to Write a Good README
● Matias Singer’s curated List of Awesome READMES
Good README Examples

22. Thanks
This presentation (excluding where
other licences are mentioned – for
example the photos – and
trademarks/logos) is licenced CC0 and
Public Domain, do with its content
what you think will help the world.
City of
Amsterdam