Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

More Decks by Raphael Pierzina

Other Decks in Programming


  1. Hi, my name is README! EuroPython - July 12, 2017

    Raphael Pierzina
  2. Thanks to the organizers and volunteers for a great event!

  3. $ whoami

  4. Hi there! I’m Raphael

  5. • Maintainer and core developer of Cookiecutter • Contributor and

    community person for pytest • Writing articles on raphael.codes • Software Engineer at moovel Group
  6. @hackebrot

  7. http://opensourcesurvey.org/2017/

  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
  9. Documentation is highly valued, but often overlooked

  10. Incomplete or outdated documentation is a pervasive problem, observed by

    93% of respondents.
  11. Licenses are by far the most important type of documentation

    to both users and contributors.
  12. Documentation helps create inclusive communities.

  13. Nearly a quarter of the open source community reads and

    writes English less than ‘very well.’
  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
  15. 1. What exactly is a README file?

  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
  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
  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
  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
  20. https://github.com/audreyr/cookiecutter

  21. https://github.com/audreyr/cookiecutter

  22. https://github.com/audreyr/cookiecutter

  23. https://github.com/pallets/flask

  24. https://github.com/django/django

  25. 2. Why is a README file important?

  26. You only get one chance to make a first impression!

  27. Success

  28. Failure

  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
  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
  31. $ pip --help @hackebrot

  32. $ man curl @hackebrot

  33. #DocsOrItDidntHappen

  34. You're not alone. Words are work.

  35. Sometimes they're harder work than code, since they don't neatly

    compile into binaries.
  36. But they're not as hard as you think.

  37. The main thing to remember is that the efforts need

    to be collaborative, scalable, and simple.
  38. https://opensource.com/business/15/8/docs- or-it-didnt-happen @hackebrot

  39. 3. What makes a good README?

  40. Empathy

  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
  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
  43. https://github.com/hackebrot/poyo

  44. Prerequisites • Supported operating systems • Supported Python versions •

    Required dependencies @hackebrot
  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
  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
  47. https://github.com/hackebrot/jinja2-time

  48. https://github.com/hackebrot/go-librariesio

  49. Features • List a handful of cool features to get

    potential users interested in your project • But don’t list all of them ⚠ @hackebrot
  50. https://github.com/pytest-dev/ cookiecutter-pytest-plugin

  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
  52. https://github.com/hackebrot/pytest-cookies

  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
  54. 64% say an open source license is very important in

    deciding whether to use a project.
  55. And 67% say it is very important in deciding whether

    to contribute.
  56. Troubleshooting • FAQs section in your documentation • Issue tracker

    and pull requests • Community chat (IRC, Gitter, Slack, …) @hackebrot
  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
  58. https://github.com/pypa/pip

  59. 4. Things you don’t want in your README

  60. Just read the code!

  61. easily, obviously, just

  62. 5. Improving your projects’ READMEs

  63. Encourage your users to submit patches to documentation!

  64. http://www.writethedocs.org/guide/writing/ beginners-guide-to-docs/ @hackebrot

  65. https://opensource.com/open-organization/ 17/1/repo-tells-a-story @hackebrot

  66. http://www.writethedocs.org/conf/eu/2017/

  67. None
  68. If you or your company are using Cookiecutter, please support

    its development! patreon.com/hackebrot @hackebrot
  69. @hackebrot