Hi, my name is README! - WriteTheDocs 2017

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/

F6e87b8993f94c06de18c85d1b3b7fb2?s=128

Raphael Pierzina

September 12, 2017
Tweet

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! ✋

  8. None
  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. 5. Improving your projects’ READMEs

  68. Good READMEs are a key component for successful projects.

  69. Do peer reviews for your documentation.

  70. Work on your documentation at conference sprints.

  71. Encourage your users to submit patches to documentation! +

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

  73. “Docs or it didn't happen” by @thatdocslady https://opensource.com/business/15/8/ docs-or-it-didnt-happen @hackebrot

  74. “What your code repository says about you” by @LauritaApplez https://opensource.com/open-organization/

    17/1/repo-tells-a-story @hackebrot
  75. 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
  76. None
  77. None
  78. @hackebrot