Hi, my name is README! - WriteTheDocs 2017

When starting a new project, developers, myself included, usually get right into hacking things, like tinkering with libraries, that we would like to learn or solving a particular problem as quickly a possible. Occasionally we also decide to publish the resulting project to a software repository such as PyPI for Python or NPM for Node.js etc., so that others can use our nifty code, submit a pull request and maybe even form a community around the project.

As the creator, you might be lucky and someone will find your project on the front-page of GitHub or maybe eben Hacker News or Reddit. What happens next is on you really. But what does that mean?

Before jumping right to the command line and installing your package, those who are interested usually try to find out what problems the project is solving and how it can help them with their own. That's what your README file is for - it's most likely the first thing potential users read, that you control.

A good README briefly and concisely explains what your software does, how it can be installed and what API it exposes. You also want to provide information on the requirements, the license it uses and how the project is managed. Who are you? How to get in touch to report problems and give feedback? Where can potential users find the Code of Conduct for your project?

This talk is for everyone who is interested in working on open source projects and wants to know how documentation can help newcomers and more experienced users use your code and to encourage them to engage in the community.

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

Transcript

1. Hi, my name is README! WriteTheDocs - September 12, 2017 Raphael Pierzina
2. Thanks to the organizers and volunteers for this great conference!
3. $ whoami
4. Hi there! I’m Raphael
5. • Maintainer and core developer of Cookiecutter and pytest and related projects • I also write, speak, and tweet about these and other open source projects • Writing articles on my blog at raphael.codes
6. What is a maintainer?
7. I’m a Documentarian! ✋
9. @hackebrot
10. http://opensourcesurvey.org/2017/ @hackebrot
11. 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
12. Documentation is highly valued, but often overlooked
13. Incomplete or outdated documentation is a pervasive problem, observed by 93% of respondents.
14. Yet only 60% of contributors say they rarely or never contribute to documentation.
15. Licenses are by far the most important type of documentation to both users and contributors.
16. Documentation helps create inclusive communities.
17. Nearly a quarter of the open source community reads and writes English less than ‘very well.’
18. 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
19. 1. What exactly is a README file?
20. 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
21. 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
22. …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 run into an issue when using your project (and might be frustrated ) @hackebrot
23. …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
24. https://github.com/audreyr/cookiecutter @hackebrot
25. https://github.com/audreyr/cookiecutter @hackebrot
26. https://github.com/audreyr/cookiecutter @hackebrot
27. https://github.com/pallets/flask @hackebrot
28. https://github.com/django/django @hackebrot
29. 2. Why is a README file so important?
30. You only get one chance to make a first impression!
31. Success
32. Failure
33. 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 that would otherwise help you improve the project • Without users, you will most probably struggle to find people who want to contribute to your project @hackebrot
34. 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
35. $ pip --help @hackebrot
36. $ man curl @hackebrot
37. #DocsOrItDidntHappen (Hi Mikey ()
38. You're not alone. Words are work.
39. Sometimes they're harder work than code, since they don't neatly compile into binaries.
40. But they're not as hard as you think.
41. The main thing to remember is that the efforts need to be collaborative, scalable, and simple.
42. 3. What makes a good README?
43. Empathy
44. The ability to understand and share the feelings of another.
45. … for newcomers … for experienced users … for contributors … for fellow maintainers
46. 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
47. 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
48. https://github.com/hackebrot/poyo @hackebrot
49. Prerequisites • Supported operating systems • Supported programming language versions • Required dependencies @hackebrot
50. 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
51. 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
52. https://github.com/hackebrot/jinja2-time @hackebrot
53. https://github.com/hackebrot/go-librariesio @hackebrot
54. Features • List a handful of cool features to get potential users interested in your project • But don’t list all of them ⚠ @hackebrot
55. https://github.com/pytest-dev/ cookiecutter-pytest-plugin @hackebrot
56. Getting started • Give a brief example for how to use your project • Make sure the code actually works ⚠ • Link to the tutorials section of your docs @hackebrot
57. https://github.com/hackebrot/pytest-cookies @hackebrot
58. 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
59. 64% say an open source license is very important in deciding whether to use a project.
60. And 67% say it is very important in deciding whether to contribute.
61. Troubleshooting • FAQs section in your documentation • Issue tracker and pull requests • Community chat (IRC, Gitter, Slack, …) @hackebrot
62. 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
63. https://github.com/pypa/pip @hackebrot
64. 4. Things you don’t want in your README
65. Just read the code!
66. easily, obviously, just
67. …
68. 5. Improving your projects’ READMEs
69. Good READMEs are a key component for successful projects.
70. Do peer reviews for your documentation.
71. Work on your documentation at conference sprints.
72. Encourage your users to submit patches to documentation! +
73. http://www.writethedocs.org/guide/ writing/beginners-guide-to-docs/ @hackebrot
74. “Docs or it didn't happen” by @thatdocslady https://opensource.com/business/15/8/ docs-or-it-didnt-happen @hackebrot
75. “What your code repository says about you” by @LauritaApplez https://opensource.com/open-organization/ 17/1/repo-tells-a-story @hackebrot
76. Hire me! I am interested in developer advocate opportunities with companies that... • see developer advocacy under engineering rather than pre-sales • recognize the importance of diversity & inclusion • create open source software and contribute upstream If you or your company are hiring developer advocates in Berlin or for remote work, I'd love to hear from you via email to raphael@hackebrot.de @hackebrot
79. @hackebrot