The document discusses readme driven development and how to write effective readmes. It advocates writing the readme first to serve as a design document and roadmap for a project. It provides tips for readme structure and formatting, including using Markdown, limiting headings, highlighting code, and using proper punctuation. It also offers advice for writing style such as maintaining coherent state, understanding your audience, eliminating repetition, varying sentence structure, and avoiding the passive voice.

1. Readme Driven
Development
(and how to be a better writer)
Mark Rickerby

3. UPPERCASE
Traditionally used to denote
human readable files

4. README FAQ
INSTALL LICENSE
AUTHORS CHANGELOG
NEWS TODO

5. Read me!
A call to action

6. Traditional view:
Roadmap of a project

7. Traditional view:
Explain file structure

8. Traditional view:
Write at the last minute

11. Modern view:
Statement of intent

12. Modern view:
Design document

13. Modern view:
Write your Readme first

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

15. Mise en place
www.antoniotahan.com

16. Introduction
One paragraph summary

17. Introduction
[W] is an [X] that does [Y]
through [Z]

18. Getting Started
Explain the steps to install
and link to further info

19. Getting Started
Show usage examples

20. Explore your API
Write from a user
perspective

21. ### 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();
```

22. ### 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();
```

23. Good style
matters

24. Use Markdown
Or one of many alternatives

25. Sections as a guide
Introduction • Summary
Installation • Downloads • FAQ
Getting Started • Examples
Contributors

26. Structure
Limit headings to
H2 & H3 only

27. Formatting
Use code to highlight
keywords and examples

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

29. Punctuation
Use en dash correctly:
April–May
Sydney–Melbourne
Bose–Einstein

30. Punctuation
Use em dash correctly:
To break a thought—in a stronger way
than using parentheses—an em dash
should be used.

31. Writing well

32. Information that is necessary for
successful communication
Information that
is helpful
but not
crucial
Nice to
know

33. Maintain coherent
state
Don’t assume knowledge
that doesn’t exist yet

34. Understand tone
Use the right language for
the audience

35. https://github.com/play/play
“It’s true. It’s in a README.”

36. https://github.com/chrisboulton/php-resque
Lies! Lies!

37. Eliminate
repetition
Avoid using the same word
or phrase over and over

38. Vary sentence
structure
Helps reading flow

39. Avoid the passive
“The chicken crossed the road.”
vs
“The road was crossed by the
chicken.”

40. “Never use a long
word when a short
one will do”
– George Orwell

41. Driving
projects with
writing

43. Crowdfunding

45. A model for
successful
collaboration?

49. https://github.com/xenph/ignition

50. Thank you.