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

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 consumability blah blah blah blah bah @ddbeck

Let's talk about CONFIDENCE @ddbeck

>200 README s @ddbeck @ddbeck

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

Content What topics does the file cover? What links does this file have? What images does the file have? @ddbeck

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

The Bad News README quality varies. There are few conventions. READMEs are missing information. @ddbeck

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

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

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

The Good News README quality varies. There are few conventions. READMEs are missing information. @ddbeck

The README Renaissance @ddbeck @ddbeck

The Typical README A Markdown file Jargon-filled description of the project A random selection of topics @ddbeck @ddbeck

1. Identify the project. 2. Evaluate the project. 3. Use the project (once). 4. Engage with the project. @ddbeck

Let's do the work. @ddbeck @ddbeck

github.com/ddbeck/readme-checklist @ddbeck

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

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

Evaluate How does this project help? What are the terms of use? @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. @ddbeck

Mad Libs With <project> you can <verb> <noun>… <project> helps you <verb> <noun>… Unlike <alternative>, <project> <verbs> <noun>… @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. @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. @ddbeck

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

Use 1. Name your prerequisites. 2. List your installation steps. 3. Show that it works once. @ddbeck

Engage Where is the documentation? Where do contributions go? Where are the people? @ddbeck

github.com/nayafia/contributing-template @ddbeck

1. Identify the project. 2. Evaluate the project. 3. Use the project (once). 4. Engage with the project. @ddbeck

Let's talk about CONFIDENCE @ddbeck