Hi, my name is README! - EuroPython 2017

Slide 1

Slide 1 text

Hi, my name is README! EuroPython - July 12, 2017 Raphael Pierzina

Slide 2

Slide 2 text

Thanks to the organizers and volunteers for a great event! !

Slide 3

Slide 3 text

$ whoami

Slide 4

Slide 4 text

Hi there! I’m Raphael

Slide 5

Slide 5 text

• Maintainer and core developer of Cookiecutter • Contributor and community person for pytest • Writing articles on raphael.codes • Software Engineer at moovel Group

Slide 6

Slide 6 text

@hackebrot

Slide 7

Slide 7 text

http://opensourcesurvey.org/2017/

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

Documentation is highly valued, but often overlooked

Slide 10

Slide 10 text

Incomplete or outdated documentation is a pervasive problem, observed by 93% of respondents.

Slide 11

Slide 11 text

Licenses are by far the most important type of documentation to both users and contributors.

Slide 12

Slide 12 text

Documentation helps create inclusive communities.

Slide 13

Slide 13 text

Nearly a quarter of the open source community reads and writes English less than ‘very well.’

Slide 14

Slide 14 text

Agenda 1. What exactly is a README ﬁle? 2. Why is a README ﬁle so important? 3. What makes a good README? 4. Things you don’t want in your README 5. Improving your projects’ READMEs

Slide 15

Slide 15 text

1. What exactly is a README file?

Slide 16

Slide 16 text

A README is… • a text ﬁle 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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

…and also… • Makes your project’s ﬁrst 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

Slide 19

Slide 19 text

…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

Slide 20

Slide 20 text

https://github.com/audreyr/cookiecutter

Slide 21

Slide 21 text

https://github.com/audreyr/cookiecutter

Slide 22

Slide 22 text

https://github.com/audreyr/cookiecutter

Slide 23

Slide 23 text

https://github.com/pallets/ﬂask

Slide 24

Slide 24 text

https://github.com/django/django

Slide 25

Slide 25 text

2. Why is a README file important?

Slide 26

Slide 26 text

You only get one chance to make a first impression!

Slide 27

Slide 27 text

Success

Slide 28

Slide 28 text

Failure

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

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 ﬁle contents in their text editor or IDE of choice @hackebrot

Slide 31

Slide 31 text

$ pip --help @hackebrot

Slide 32

Slide 32 text

$ man curl @hackebrot

Slide 33

Slide 33 text

#DocsOrItDidntHappen

Slide 34

Slide 34 text

You're not alone. Words are work.

Slide 35

Slide 35 text

Sometimes they're harder work than code, since they don't neatly compile into binaries.

Slide 36

Slide 36 text

But they're not as hard as you think.

Slide 37

Slide 37 text

The main thing to remember is that the efforts need to be collaborative, scalable, and simple.

Slide 38

Slide 38 text

https://opensource.com/business/15/8/docs- or-it-didnt-happen @hackebrot

Slide 39

Slide 39 text

3. What makes a good README?

Slide 40

Slide 40 text

Empathy

Slide 41

Slide 41 text

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

Slide 42

Slide 42 text

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

Slide 43

Slide 43 text

https://github.com/hackebrot/poyo

Slide 44

Slide 44 text

Prerequisites • Supported operating systems • Supported Python versions • Required dependencies @hackebrot

Slide 45

Slide 45 text

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

Slide 46

Slide 46 text

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

Slide 47

Slide 47 text

https://github.com/hackebrot/jinja2-time

Slide 48

Slide 48 text

https://github.com/hackebrot/go-librariesio

Slide 49

Slide 49 text

Features • List a handful of cool features to get potential users interested in your project • But don’t list all of them ⚠ @hackebrot

Slide 50

Slide 50 text

https://github.com/pytest-dev/ cookiecutter-pytest-plugin

Slide 51

Slide 51 text

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

Slide 52

Slide 52 text

https://github.com/hackebrot/pytest-cookies

Slide 53

Slide 53 text

License • What’s the license of your project? Where to ﬁnd the full license text? • Without a license people won’t be able to use, modify and build on top of your project @hackebrot

Slide 54

Slide 54 text

64% say an open source license is very important in deciding whether to use a project.

Slide 55

Slide 55 text

And 67% say it is very important in deciding whether to contribute.

Slide 56

Slide 56 text

Troubleshooting • FAQs section in your documentation • Issue tracker and pull requests • Community chat (IRC, Gitter, Slack, …) @hackebrot

Slide 57

Slide 57 text

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

Slide 58

Slide 58 text

https://github.com/pypa/pip

Slide 59

Slide 59 text

4. Things you don’t want in your README

Slide 60

Slide 60 text

Just read the code!

Slide 61

Slide 61 text

easily, obviously, just

Slide 62

Slide 62 text

…

Slide 63

Slide 63 text

5. Improving your projects’ READMEs

Slide 64

Slide 64 text

Encourage your users to submit patches to documentation!

Slide 65

Slide 65 text

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

Slide 66

Slide 66 text

https://opensource.com/open-organization/ 17/1/repo-tells-a-story @hackebrot

Slide 67

Slide 67 text

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

Slide 68

Slide 68 text

✏

Slide 69

Slide 69 text

No content

Slide 70

Slide 70 text

If you or your company are using Cookiecutter, please support its development! patreon.com/hackebrot @hackebrot

Slide 71

Slide 71 text

@hackebrot