Hi, my name is README! - EuroPython 2017

Hi, my name is README! - EuroPython 2017

With more and more repositories moving to GitHub, chances are a README file is the first thing you see when hearing about a new project. Yet as developers, it seems, we sometimes do not care enough about one of the most important things in running a community: Documentation. Your project's README file is documentation and if done right, it can be the one key factor in getting people to use your project and even contribute to it.

#WriteTheDocs #DocsOrItDidntHappen



Raphael Pierzina

July 12, 2017


  1. 5.

    • Maintainer and core developer of Cookiecutter • Contributor and

    community person for pytest • Writing articles on raphael.codes • Software Engineer at moovel Group
  2. 8.

    Overview • 5,500 randomly sampled respondents • sourced from over

    3,800 open source repositories on GitHub.com • and over 500 responses from a non-random sample of communities that work on other platforms @hackebrot
  3. 13.

    Nearly a quarter of the open source community reads and

    writes English less than ‘very well.’
  4. 14.

    Agenda 1. What exactly is a README file? 2. Why

    is a README file so important? 3. What makes a good README? 4. Things you don’t want in your README 5. Improving your projects’ READMEs
  5. 16.

    A README is… • a text file that lives next

    to your code • Most projects use markdown or reStructuredText • If your project is hosted on GitHub/GitLab or a similar platform it will be rendered to HTML @hackebrot
  6. 17.

    pytest-emoji/ ├── LICENSE ├── MANIFEST.in ├── README.rst ├── appveyor.yml ├──

    docs │ └── index.md ├── mkdocs.yml ├── pytest_emoji.py ├── setup.py ├── tests │ ├── conftest.py │ └── test_emoji.py └── tox.ini py @hackebrot
  7. 18.

    …and also… • Makes your project’s first impression and as

    such can make a big difference for the adoption of your project • First contact point for users when they ran into an issue when using your project (and might be frustrated ) @hackebrot
  8. 19.

    …but… • READMEs can look very different for different projects

    • Communities use READMEs for different purposes • But ultimately every project will use a README to grow its user base and increase adoption @hackebrot
  9. 27.
  10. 28.
  11. 29.

    What does that mean? • If you fail to appeal

    to potential users, people won’t use your project • If no one uses your project, you won’t get any feedback which would otherwise help you improve • Without users you probably won’t attract people who want to contribute to your project @hackebrot
  12. 30.

    But there’s more… • A README is documentation and it

    will be consumed in various different ways • Some people will read it on GitHub/GitLab etc. • Others will read the actual file contents in their text editor or IDE of choice @hackebrot
  13. 37.

    The main thing to remember is that the efforts need

    to be collaborative, scalable, and simple.
  14. 40.
  15. 41.

    Tell a story • Describe what problem your project solves,

    how it works but also why you started it • Explain how to install the project and how to get started • Give an outlook for the direction of the project and invite users to contribute and impact the direction @hackebrot
  16. 42.

    Set expectations • Explain what problems your project doesn’t solve

    • If you can, point them to other similar projects that they might want to check out • Let potential users know how mature your project is: Is it in an early development stage or production ready? @hackebrot
  17. 45.

    if sys.platform in ('win32', 'cygwin', 'cli'): raise RuntimeError('foobar does not

    support Windows at the moment') vi = sys.version_info if vi < (3, 5): raise RuntimeError('foobar requires Python 3.5 or greater’) if vi[:2] == (3, 6): if vi.releaselevel == 'beta' and vi.serial < 3: raise RuntimeError('foobar requires Python 3.5 or 3.6b3 or greater') py @hackebrot
  18. 46.

    Installation • Concise instructions how to install the software •

    Mention only the preferred method for installation • If there are other ways to install your project, link to an according section in your docs @hackebrot
  19. 49.

    Features • List a handful of cool features to get

    potential users interested in your project • But don’t list all of them ⚠ @hackebrot
  20. 51.

    Getting started • Give a brief example for how to

    use your project • Show potential users how easy it is to use • Make sure the code actually works ⚠ @hackebrot
  21. 53.

    License • What’s the license of your project? Where to

    find the full license text? • Without a license people won’t be able to use, modify and build on top of your project @hackebrot
  22. 54.

    64% say an open source license is very important in

    deciding whether to use a project.
  23. 56.

    Troubleshooting • FAQs section in your documentation • Issue tracker

    and pull requests • Community chat (IRC, Gitter, Slack, …) @hackebrot
  24. 57.

    Community • Who are the people behind the project? •

    How to contribute to your project? • How to become a core team member? • Contributor Code of Conduct @hackebrot
  25. 62.

  26. 68.

  27. 69.
  28. 70.

    If you or your company are using Cookiecutter, please support

    its development! patreon.com/hackebrot @hackebrot