Hi, my name is README! - WriteTheDocs 2017

Slide 1

Slide 1 text

Hi, my name is README! WriteTheDocs - September 12, 2017 Raphael Pierzina

Slide 2

Slide 2 text

Thanks to the organizers and volunteers for this great conference!

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

Slide 6

Slide 6 text

What is a maintainer?

Slide 7

Slide 7 text

I’m a Documentarian! ✋

Slide 8

Slide 8 text

No content

Slide 9

Slide 9 text

@hackebrot

Slide 10

Slide 10 text

http://opensourcesurvey.org/2017/ @hackebrot

Slide 11

Slide 11 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 12

Slide 12 text

Documentation is highly valued, but often overlooked

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

Yet only 60% of contributors say they rarely or never contribute to documentation.

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

Documentation helps create inclusive communities.

Slide 17

Slide 17 text

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

Slide 18

Slide 18 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 19

Slide 19 text

1. What exactly is a README file?

Slide 20

Slide 20 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 21

Slide 21 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 22

Slide 22 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 run into an issue when using your project (and might be frustrated ) @hackebrot

Slide 23

Slide 23 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 24

Slide 24 text

https://github.com/audreyr/cookiecutter @hackebrot

Slide 25

Slide 25 text

https://github.com/audreyr/cookiecutter @hackebrot

Slide 26

Slide 26 text

https://github.com/audreyr/cookiecutter @hackebrot

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

https://github.com/django/django @hackebrot

Slide 29

Slide 29 text

2. Why is a README file so important?

Slide 30

Slide 30 text

You only get one chance to make a first impression!

Slide 31

Slide 31 text

Success

Slide 32

Slide 32 text

Failure

Slide 33

Slide 33 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 that would otherwise help you improve the project • Without users, you will most probably struggle to ﬁnd people who want to contribute to your project @hackebrot

Slide 34

Slide 34 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 35

Slide 35 text

$ pip --help @hackebrot

Slide 36

Slide 36 text

$ man curl @hackebrot

Slide 37

Slide 37 text

#DocsOrItDidntHappen (Hi Mikey ()

Slide 38

Slide 38 text

You're not alone. Words are work.

Slide 39

Slide 39 text

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

Slide 40

Slide 40 text

But they're not as hard as you think.

Slide 41

Slide 41 text

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

Slide 42

Slide 42 text

3. What makes a good README?

Slide 43

Slide 43 text

Empathy

Slide 44

Slide 44 text

The ability to understand and share the feelings of another.

Slide 45

Slide 45 text

… for newcomers … for experienced users … for contributors … for fellow maintainers

Slide 46

Slide 46 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 47

Slide 47 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 48

Slide 48 text

https://github.com/hackebrot/poyo @hackebrot

Slide 49

Slide 49 text

Prerequisites • Supported operating systems • Supported programming language versions • Required dependencies @hackebrot

Slide 50

Slide 50 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 51

Slide 51 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 52

Slide 52 text

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

Slide 53

Slide 53 text

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

Slide 54

Slide 54 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 55

Slide 55 text

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

Slide 56

Slide 56 text

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

Slide 57

Slide 57 text

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

Slide 58

Slide 58 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 59

Slide 59 text

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

Slide 60

Slide 60 text

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

Slide 61

Slide 61 text

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

Slide 62

Slide 62 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 63

Slide 63 text

https://github.com/pypa/pip @hackebrot

Slide 64

Slide 64 text

4. Things you don’t want in your README

Slide 65

Slide 65 text

Just read the code!

Slide 66

Slide 66 text

easily, obviously, just

Slide 67

Slide 67 text

…

Slide 68

Slide 68 text

5. Improving your projects’ READMEs

Slide 69

Slide 69 text

Good READMEs are a key component for successful projects.

Slide 70

Slide 70 text

Do peer reviews for your documentation.

Slide 71

Slide 71 text

Work on your documentation at conference sprints.

Slide 72

Slide 72 text

Encourage your users to submit patches to documentation! +

Slide 73

Slide 73 text

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

Slide 74

Slide 74 text

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

Slide 75

Slide 75 text

“What your code repository says about you” by @LauritaApplez https://opensource.com/open-organization/ 17/1/repo-tells-a-story @hackebrot

Slide 76

Slide 76 text

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