readme driven development

Readme Driven Development

(and how to be a better writer)

Mark Rickerby

UPPERCASETraditionally used to denotehuman readable !les

READMEINSTALLAUTHORSNEWS

FAQLICENSECHANGELOGTODO

Read me!A call to action

Traditional view:

Roadmap of a project

Traditional view:

Explain !le structure

Traditional view:

Write at the last minute

Modern view:

Statement of intent

Modern view:

Design document

Modern view:

Write your Readme !rst

“It rewards you for keeping libraries small and modularized” – Tom Preston Werner

www.antoniotahan.com

Mise en place

Introduction

One paragraph summary

Introduction

[W] is an [X] that does [Y] through [Z]

Getting Started

Explain the steps to install and link to further info

Getting Started

Show usage examples

Explore your API

Write from a user perspective

### POST Method

Call the `post()` method to make an HTTP post request:

```$http = new Net_Http();

$http->post($uri, $data);

if ($http->getStatus() == 201) $body = $http->getBody();```

### POST Method

Call the `post()` method to make an HTTP post request:

```$http = new Net_Http();

$response = $http->post($uri, $data);

if ($response->getStatus() == 201) $body = $response->getBody();```

Good style matters

Use Markdown

Or one of many alternatives

Sections as a guide

Introduction • Summary Installation • Downloads • FAQ

Getting Started • Examples Contributors

Structure

Limit headings toH2 & H3 only

Formatting

Use code to highlight keywords and examples

Punctuation

Use real quotation marks:“double” or ‘single’

PunctuationUse en dash correctly:

April–MaySydney–Melbourne

Bose–Einstein

PunctuationUse em dash correctly:

To break a thought—in a stronger way than using parentheses—an em dash

should be used.

Writing well

Information that is necessary for successful communication

Information thatis helpfulbut notcrucial

Nice toknow

Maintain coherent state

Don’t assume knowledge that doesn’t exist yet

Understand tone

Use the right language for the audience

https://github.com/play/play

“It’s true. It’s in a README.”

https://github.com/chrisboulton/php-resque

Lies! Lies!

Eliminate repetition

Avoid using the same word or phrase over and over

Vary sentence structure

Helps reading "ow

Avoid the passive

“The chicken crossed the road.”vs

“The road was crossed by the chicken.”

“Never use a long word when a short

one will do”– George Orwell

Driving projects with

writing

Crowdfunding

A model for successful

collaboration?

https://github.com/xenph/ignition

Thank you.