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

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