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

https://ep2017.europython.eu/conference/talks/hi-my-name-is-readme-a-look-at-why-docs-are-so-important

Raphael Pierzina

July 12, 2017
Tweet

More Decks by Raphael Pierzina

Other Decks in Programming

Transcript

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

    View Slide

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

    View Slide

  3. $ whoami

    View Slide

  4. Hi there! I’m
    Raphael

    View Slide

  5. • Maintainer and core developer of Cookiecutter
    • Contributor and community person for pytest
    • Writing articles on raphael.codes
    • Software Engineer at moovel Group

    View Slide

  6. @hackebrot

    View Slide

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

    View Slide

  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

    View Slide

  9. Documentation is highly valued, but
    often overlooked

    View Slide

  10. Incomplete or outdated documentation
    is a pervasive problem, observed by
    93% of respondents.

    View Slide

  11. Licenses are by far the most
    important type of documentation to
    both users and contributors.

    View Slide

  12. Documentation helps create
    inclusive communities.

    View Slide

  13. Nearly a quarter of the open source
    community reads and writes English
    less than ‘very well.’

    View Slide

  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

    View Slide

  15. 1. What exactly
    is a README file?

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  25. 2. Why is a README
    file important?

    View Slide

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

    View Slide

  27. Success

    View Slide

  28. Failure

    View Slide

  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

    View Slide

  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

    View Slide

  31. $ pip --help
    @hackebrot

    View Slide

  32. $ man curl
    @hackebrot

    View Slide

  33. #DocsOrItDidntHappen

    View Slide

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

    View Slide

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

    View Slide

  36. But they're not as
    hard as you think.

    View Slide

  37. The main thing to remember
    is that the efforts need
    to be collaborative,
    scalable, and simple.

    View Slide

  38. https://opensource.com/business/15/8/docs-
    or-it-didnt-happen
    @hackebrot

    View Slide

  39. 3. What makes a
    good README?

    View Slide

  40. Empathy

    View Slide

  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

    View Slide

  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

    View Slide

  43. https://github.com/hackebrot/poyo

    View Slide

  44. Prerequisites
    • Supported operating systems
    • Supported Python versions
    • Required dependencies
    @hackebrot

    View Slide

  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

    View Slide

  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

    View Slide

  47. https://github.com/hackebrot/jinja2-time

    View Slide

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

    View Slide

  49. Features
    • List a handful of cool features to get potential users
    interested in your project
    • But don’t list all of them ⚠
    @hackebrot

    View Slide

  50. https://github.com/pytest-dev/
    cookiecutter-pytest-plugin

    View Slide

  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

    View Slide

  52. https://github.com/hackebrot/pytest-cookies

    View Slide

  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

    View Slide

  54. 64% say an open source license is
    very important in deciding whether
    to use a project.

    View Slide

  55. And 67% say it is very important in
    deciding whether to contribute.

    View Slide

  56. Troubleshooting
    • FAQs section in your documentation
    • Issue tracker and pull requests
    • Community chat (IRC, Gitter, Slack, …)
    @hackebrot

    View Slide

  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

    View Slide

  58. https://github.com/pypa/pip

    View Slide

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

    View Slide

  60. Just read the code!

    View Slide

  61. easily,
    obviously,
    just

    View Slide


  62. View Slide

  63. 5. Improving your
    projects’ READMEs

    View Slide

  64. Encourage your users
    to submit patches to
    documentation!

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide


  68. View Slide

  69. View Slide

  70. If you or your company are using
    Cookiecutter, please support its
    development!
    patreon.com/hackebrot
    @hackebrot

    View Slide

  71. @hackebrot

    View Slide