readme driven development
DESCRIPTION
TRANSCRIPT
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
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.