Hi, my name is README!


When starting a new project, developers, myself included, usually get right into hacking things, like tinkering with libraries, that we would like to learn or solving a particular problem as quickly a possible. Occasionally we also decide to publish the resulting project to a software repository such as PyPI for Python or NPM for Node.js etc., so that others can use our nifty code, submit a pull request and maybe even form a community around the project.

As the creator, you might be lucky and someone will find your project on the front-page of GitHub or maybe eben Hacker News or Reddit. What happens next is on you really. But what does that mean?

Before jumping right to the command line and installing your package, those who are interested usually try to find out what problems the project is solving and how it can help them with their own. That's what your README file is for - it's most likely the first thing potential users read, that you control.

A good README briefly and concisely explains what your software does, how it can be installed and what API it exposes. You also want to provide information on the requirements, the license it uses and how the project is managed. Who are you? How to get in touch to report problems and give feedback? Where can potential users find the Code of Conduct for your project?

This talk is for everyone who is interested in working on open source projects and wants to know how documentation can help newcomers and more experienced users use your code and to encourage them to engage in the community.

  • Conference: Write the Docs EU
  • Year: 2017

About the speaker

Raphael Pierzina