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 full-size slide

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

    View full-size slide

  3. Hi there! I’m
    Raphael

    View full-size slide

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

    View full-size slide

  5. http://opensourcesurvey.org/2017/

    View full-size slide

  6. 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 full-size slide

  7. Documentation is highly valued, but
    often overlooked

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  10. Documentation helps create
    inclusive communities.

    View full-size slide

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

    View full-size slide

  12. 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 full-size slide

  13. 1. What exactly
    is a README file?

    View full-size slide

  14. 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 full-size slide

  15. 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 full-size slide

  16. …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 full-size slide

  17. …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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  22. https://github.com/django/django

    View full-size slide

  23. 2. Why is a README
    file important?

    View full-size slide

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

    View full-size slide

  25. 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 full-size slide

  26. 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 full-size slide

  27. $ pip --help
    @hackebrot

    View full-size slide

  28. $ man curl
    @hackebrot

    View full-size slide

  29. #DocsOrItDidntHappen

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  35. 3. What makes a
    good README?

    View full-size slide

  36. 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 full-size slide

  37. 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 full-size slide

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

    View full-size slide

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

    View full-size slide

  40. 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 full-size slide

  41. 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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  46. 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 full-size slide

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

    View full-size slide

  48. 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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  52. 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 full-size slide

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

    View full-size slide

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

    View full-size slide

  55. Just read the code!

    View full-size slide

  56. easily,
    obviously,
    just

    View full-size slide

  57. 5. Improving your
    projects’ READMEs

    View full-size slide

  58. Encourage your users
    to submit patches to
    documentation!

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide