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
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. …
63. 5. Improving your projects’ READMEs
64. Encourage your users to submit patches to documentation!
65. http://www.writethedocs.org/guide/writing/ beginners-guide-to-docs/ @hackebrot
66. https://opensource.com/open-organization/ 17/1/repo-tells-a-story @hackebrot
67. http://www.writethedocs.org/conf/eu/2017/
68. ✏
70. If you or your company are using Cookiecutter, please support its development! patreon.com/hackebrot @hackebrot
71. @hackebrot