write_the_readable_README.txt Daniel D. Beck @ddbeck Write the - - PowerPoint PPT Presentation

▶
write the readable readme txt
SMART_READER_LITE
LIVE PREVIEW

write_the_readable_README.txt Daniel D. Beck @ddbeck Write the - - PowerPoint PPT Presentation

May 10, 2023 357 likes •667 views

write_the_readable_README.txt Daniel D. Beck @ddbeck Write the Docs NA May 23, 2016 A simple, easy-to-consume, self-wrapping blah blah object for collection from blah blah pseudo-trees with support for automatic blah-shifting

slide-1
SLIDE 1

write_the_readable_README.txt

Daniel D. Beck @ddbeck Write the Docs NA – May 23, 2016

slide-2
SLIDE 2

@ddbeck

A simple, easy-to-consume, self-wrapping blah blah object for collection from blah blah pseudo-trees with support for automatic blah-shifting consumability blah blah blah blah bah

slide-3
SLIDE 3

@ddbeck

CONFIDENCE

Let's talk about

slide-4
SLIDE 4

@ddbeck

>200 READMEs

@ddbeck

slide-5
SLIDE 5

@ddbeck

Context

What kind of project is this? What other files accompany this README? What markup is this?

slide-6
SLIDE 6

@ddbeck

Content

What topics does the file cover? What links does this file have? What images does the file have?

slide-7
SLIDE 7

@ddbeck

Subjective

What was good? What was bad? How did the README make me feel?

slide-8
SLIDE 8

@ddbeck

The Bad News

README quality varies. There are few conventions. READMEs are missing information.

slide-9
SLIDE 9

@ddbeck

17%* of READMEs don't want you to know
 the project's name.

slide-10
SLIDE 10

@ddbeck

31% of READMEs don't want you to know
 what the project is.

slide-11
SLIDE 11

@ddbeck

46% of READMEs don't want you to know
 where the project is.

slide-12
SLIDE 12

@ddbeck

The Good News

README quality varies. There are few conventions. READMEs are missing information.

slide-13
SLIDE 13

@ddbeck

The README Renaissance

@ddbeck

slide-14
SLIDE 14

@ddbeck

A Markdown file Jargon-filled description of the project A random selection of topics

The Typical README

@ddbeck

slide-15
SLIDE 15

@ddbeck

  • 1. Identify the project.
  • 2. Evaluate the project.
  • 3. Use the project (once).
  • 4. Engage with the project.
slide-16
SLIDE 16

@ddbeck

Let's do the work.

@ddbeck

slide-17
SLIDE 17

@ddbeck

github.com/ddbeck/readme-checklist

slide-18
SLIDE 18

@ddbeck

Context

What kind of project is this? What other files accompany this README? What markup is this?

slide-19
SLIDE 19

@ddbeck

Identify

What's the name of the project? What's the URL for the project? Who's the author of the project?

slide-20
SLIDE 20

@ddbeck

Evaluate

How does this project help? What are the terms of use?

slide-21
SLIDE 21

@ddbeck

A simple, easy-to-consume, self- wrapping parthenocarpic object for collection from baccate pseudo-trees with support for automatic color-shifting consumability status indication.

slide-22
SLIDE 22

@ddbeck

Mad Libs

With <project> you can <verb> <noun>… <project> helps you <verb> <noun>… Unlike <alternative>, <project> <verbs> <noun>…

slide-23
SLIDE 23

@ddbeck

With Banana, you can have a

  • snack. You'll like Banana

because Banana turns yellow when you can eat it. Banana's better than Orange because you can open it without a knife. Unlike Peach, Banana doesn't have a pit.

slide-24
SLIDE 24

@ddbeck

With Banana, you can have a

  • snack. You'll like Banana

because Banana turns yellow when you can eat it. Banana's better than Orange because you can open it without a knife. Unlike Peach, Banana doesn't have a pit.

slide-25
SLIDE 25

@ddbeck

Evaluate

How does this project help? What are the terms of use?

slide-26
SLIDE 26

@ddbeck

Use

  • 1. Name your prerequisites.
  • 2. List your installation steps.
  • 3. Show that it works once.
slide-27
SLIDE 27

@ddbeck

Engage

Where is the documentation? Where do contributions go? Where are the people?

slide-28
SLIDE 28

@ddbeck

github.com/nayafia/contributing-template

slide-29
SLIDE 29

@ddbeck

  • 1. Identify the project.
  • 2. Evaluate the project.
  • 3. Use the project (once).
  • 4. Engage with the project.
slide-30
SLIDE 30

@ddbeck

CONFIDENCE

Let's talk about