Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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.


Raphael Pierzina

September 12, 2017

More Decks by Raphael Pierzina

Other Decks in Technology


  1. • 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
  2. 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
  3. Nearly a quarter of the open source community reads and

    writes English less than ‘very well.’
  4. 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
  5. 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
  6. 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
  7. …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
  8. …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
  9. 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
  10. 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
  11. The main thing to remember is that the efforts need

    to be collaborative, scalable, and simple.
  12. 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
  13. 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
  14. 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
  15. 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
  16. Features • List a handful of cool features to get

    potential users interested in your project • But don’t list all of them ⚠ @hackebrot
  17. 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
  18. 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
  19. 64% say an open source license is very important in

    deciding whether to use a project.
  20. Troubleshooting • FAQs section in your documentation • Issue tracker

    and pull requests • Community chat (IRC, Gitter, Slack, …) @hackebrot
  21. 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
  22. 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 [email protected] @hackebrot