
Readme Driven Development - mojombo
http://tom.preston-werner.com/2010/08/23/readme-driven-development.html
======
clemesha
Seems that mojombo practices what he preaches. First commit by mojombo (from
march 29, 2010) of Github's Gollum wiki reads "readme driven development!"

[http://github.com/github/gollum/commit/c7875704971be998a5399...](http://github.com/github/gollum/commit/c7875704971be998a5399ce83e66a5dada03aad4)

~~~
mojombo
You may also be interested to see how the Readme evolved over time as I
implemented what I had specified.

<http://github.com/github/gollum/commits/master/README.md>

Writing your Readme first doesn't mean you should never change it. It should
grow and become even more refined, comprehensive, and accurate as you write
the code.

~~~
sr3d
self-plug:
[http://sr3d.github.com/GithubFinder/?user_id=github&repo...](http://sr3d.github.com/GithubFinder/?user_id=github&repo=gollum)

and click on README.md and you can diff to see how the README.md file changed
overtime.

A nice Readme is a good way to help people engage in the project as well. A
project with nice README and screenshots will get the attention of users
better since it's a good and direct way to explain why this project matters,
and why people should use and contribute to the project. Good readme should
also include enough details to help a new user get started, e.g. how to
compile, how to install, and how to start integrating.

Also, I watched a Google video of Brian Fitzpatrick and Ben Collins, who
developed Subversion, on how to defend open source projects from "poisonous".
Their number one rule is "When you launch a project, carefully define your
mission - and post that mission to a conspicuous web page."
([http://www.theregister.co.uk/2008/05/30/google_open_source_t...](http://www.theregister.co.uk/2008/05/30/google_open_source_talk/))
A readme can serve as a mission statement to define a clear path of the
project.

If a project is like a book, the Readme file would be the cover with all the
raves and hooks to get people to pick up the book. But as they say, "don't
judge a book by its cover", "don't judge a project by its Readme file" either.
But good readme will definitely help.

------
silentbicycle
So in a roundabout way, we're back to...design-driven design?

Writing a README early on (and figuring out your general project scope, etc.)
is a good idea, sure. Fundamentally, though, it sounds like he's just saying
that a Software Engineering Methodology(TM) is no replacement for common
sense.

When people attempt to formalize (and, often, brand & market) common sense, it
tends to substitute checklists for thought.

------
DanielStraight
This should be followed by an overview of what should be in a readme, as well
as examples of good and bad readmes.

Still, good stuff. Just leaves a few questions.

~~~
adamv
A good readme is a lot like a good manpage: <http://rtomayko.github.com/ronn/>

~~~
ekidd
I'm a huge fan of good man pages. A good man page contains a short overview,
some detailed reference documentation, and (if you're lucky) some useful
examples.

A good README, on the other hand, explains why the accompanying program is
useful, shows some examples of how to use it, and points the user towards
detailed documentation.

Now, perhaps the _ideal_ man page would also serve as a perfectly good README.
But if you do a survey of merely _good_ manpages, and use them as a standard
for writing READMEs, then you're probably going to get mediocre READMEs.
Typical Unix and Linux manpages, even the good ones, don't spend enough time
on high-level overviews and examples.

------
philwelch
Naturally, Github showcases the README on the main project page and strongly
encourages you to write one. I agree that it's a fantastic place to start.

------
mojombo
As an example of a project that was written with RDD in mind (I wrote this
while I was writing this blog post), see <http://github.com/github/gollum>.
This is my notion of the scope and specificity that a nice Readme should have.

------
benatkin
I have a hard time thinking seriously about this, because all I can think of
right now are those repos on GitHub that have nothing but a README file.

~~~
mbreese
They obviously haven't gotten to step two... writing the code.

~~~
silentbicycle
sudo apt-get install readme-compiler

(declarative programming for the rest of us!)

------
joelhaasnoot
Ah yes, does anybody else remember the glory days of shareware and freeware
dominating, sold on magazine CDs and various collections? The good software
always had an excellent, beautifully crafted readme, detailing features,
install how-to, changelog, and other wonderful details! No need for google!
Sometimes we forget there are people that operate without internet for
documentation...

------
tjpick
Seems like we're just talking about writing a spec before the code, and README
being a specific form/template/symbol for that. Starting to feel like we're
moving full circle w.r.t. agile vs process/documentation heavy methodologies.

~~~
silentbicycle
He mentioned in passing that writing a typical README requires just the right
amount of planning upfront. It was tangential to his main point, about
documentation, but I think it's a good observation.

It avoids both planning extremes: writing an incredibly detailed spec upfront
without any feedback from prototyping (waterfall), and diving in without any
planning and expecting tests to magically do your design for you (naive TDD).

It's good to having an articulate summary of your project, but for planning,
the README is just a prop. It could just as well be "whiteboard-driven design"
or whatever.

~~~
mojombo
The benefit of doing your design in a Readme over doing it on a whiteboard or
elsewhere is that it becomes a nice piece of documentation sitting right there
in the root of the project. The first place you look for an explanation of
what the project does and how to use it. Everybody wins!

~~~
silentbicycle
Oh, I don't disagree with that part at all, I just think that your aside about
it encouraging just the right amount of design upfront deserves more thought.

I tend to do design brainstorming on scratch paper, Emacs scratch buffers, and
in Prolog, but I'm already convinced about the merits of having a good README,
and would write one regardless. (Just like I write tests anyway, whether or
not I do them upfront.)

------
WorkerBee
_SCRUM ... all irrelevant unless the software we're building meets the needs
of those that are using it._

That statement misses the entire point of Scrum. What are those short
iterations for, if not to get feedback from those using the software? Why
replan at the end of every sprint, if not to know how user needs have changed
and been informed by the current software?

How is the readme so different from the sprint's user stories? Working from
the desired end docs looks like another version of the currently fashionable
"pull" methods. Not a bad one for a particular kind of project though.

------
benbjohnson
I would love to see some way to relate test cases with sections of the README.
That way you could see code coverage of your README. It's difficult to
retroactively write a README after you've written your code but it can also be
difficult to write all the code described by your README.

The README shouldn't hold every detail of your implementation but it would be
a good starting point for developers trying to find where described
functionality is located in a library.

Also, it would provide the inverse: You can see what test cases you have that
are not described in your documentation.

~~~
adorton
Docco (and its variants) do sort of what you describe:

<http://jashkenas.github.com/docco/>

I can see its usefulness in documenting test cases.

~~~
benbjohnson
That's awesome how it shows the comments and code side-by-side. The only
downside is that I have to describe the functionality while I'm writing code
instead of beforehand. Thanks, adorton.

------
rbradford
I recently used this approach to reinvigorate the development of an existing
project that has flattened out. Writing out how stuff worked then gave
indications of where we needed to improve our API and document our corner
cases.

In the end the README didn't represent the status quo but instead became what
we were aiming for. For the most part this succeeded, the main challenge I had
was persuading my collaborator to actually review what i'd written.

------
agentultra
Low-tech literate programming. Personally, I use org-files.

<http://orgmode.org/>

~~~
docgnome
Best thing about org files is they are just plain text so they work perfectly
for this.

------
_mql
So true! I've also discovered for myself that keeping a one-page document,
serving as red thread makes everything so much easier.

However at some point I wasn't satisfied with the options a regular REAMDE
offers. I wanted to write such a document in a declarative style and eliminate
the limitation of having just HTML as an output format. Luckily a friend of
mine is working on a parser that reads markup (using as much natural language
as possibe, inspired by Markdown et. al) and turns it into a data
representation (JSON) rather than pre-rendered HTML.

Straight talking: I'm using it for documenting Unveil.js
(<http://github.com/michael/unveil>), a graphic library sitting on top of
HTML5 Canvas. It just turns this
(<http://github.com/michael/unveil/blob/master/index.ndg>) into this
(<http://docs.quasipartikel.at/documents/unveil>). The goal is to use it for
on-the-fly documentation generation (along with sourcecode, or for regular
documents), without the need for statically rendered HTML files.

Here's the (on-the-fly) rendered version:
<http://docs.quasipartikel.at/#/unveil>

It's all at an early stage, but I'd love to have some discussion about such
data-driven documentation. :)

\-- Michael

------
nadam
Basically good advice, but it also depends on the project. Some projects are
too experimental for this.

My approach is the following with my startup project (but not with my day-job
project):

I start to write this: brainstorm.txt

In brainstorm.txt I don't have to be concrete and concise. I just write down
all kind of ideas.

After a while I start to write this: design.txt This is very concrete
(factual) and concise. It is not an essay, it is not written for other people.
It is just for myself: to make a conceptual skeleton. It is not too
structured, because it is impossible if it is about an innovative product. The
only way I can avoid chaos is that I apply extreme minimalism. (Minimalist
things are easier to structure, and don't need to be too structured.)
Meanwhile I start to write code, mostly bottom-up. And I continuously refine
design.txt.

The User's guide (I call the Readme User's Guide) is already a quite different
story for me. It must be written for the user and not myself. I don't like
fluffy user's guides, but still it should not be as concise and as abstract as
my notes to myself. If I would have to start with the User's Guide than my
brain would work in a 'user's guide writer mode'. For me 'engineer/hacker
mode' is different.

------
fronx
Some thoughts about READMEs in the context of open source projects:

There's no need for the README to excite me and make me want to dive deeper
into the software if there are good blog posts about actual use cases. They
would lead me to your repo where I could find out how to install it, what the
dependencies are, what kind of things can be accomplished in just a few lines
of code, and how to contribute.

But, as a developer, I don't necessarily start a new project with exactly
those points in mind -- and why should I? Most of the time, I intuitively
start somewhere in the middle and move up and down from there. It is only
after some time that I recognize what this thing actually is that I'm
building. From my point of view, that would be the appropriate time to write a
README.

------
Iter8er
Something similar for product development: Working Backwards -
[http://www.allthingsdistributed.com/2006/11/working_backward...](http://www.allthingsdistributed.com/2006/11/working_backwards.html)
Although, it has not _entirely_ worked for me.

------
grandalf
I think one big strength of RDoc over other documentation formats is that it
gives the README a fairly prominent place. Seeing a few usage examples, high
level thoughts makes using a new library _so much easier_.

------
integraleq
this is an excellent post and quite relevant. i have found this kind of
epiphany as well while writing a python based framework at my company. i would
extend the README driven approach to even suggest a developer blog driven
design methodology, since it allows for a more dynamic way to clarify points
and also add diary entries for 'thinking aloud' while you are building
complicated libraries.

~~~
raggi
no. blogs are not a substitute for documentation.

ruby has been suffering this for too long.

blogs have several problems:

\- they don't get updated \- they don't get patched \- they don't ship with
the software \- they break when the user dies / moves / leaves / changes
software \- they have a lower signal to noise ratio

~~~
steveklabnik
\- they accumulate Google juice over time, overpowering advice for newer
versions of your framework.

------
bjclark
Serious question: What does TDD, BDD, Extreme Programming, SCRUM, Standups and
all the stuff in the first paragraph have to do with writing a library or app
with proper documentation?

I'm completely lost as to how doing Extreme Programming means you don't have a
good Readme for your Git-Powered wiki with sweet API?

~~~
mojombo
All of those things are approaches to crafting better software. It is my
observation that a lot of projects developed with these methodologies still
lack proper documentation. And I see documentation, especially in the form of
a good Readme, as critical to the design, usability, and longevity of a
project.

~~~
bjclark
Do you consider projects like <http://erector.rubyforge.org/>,
<http://pivotal.github.com/jasmine/user-guide.html>, or
<http://github.com/pivotal/cedar> to have good documentation?

~~~
mojombo
Sure. The documentation for those projects looks great!

------
gnatinator
Excellent concept. Very logical and seemingly effective way of writing a
specification.

I will be trying this on my next project!

------
c0ffeeadd1c7
next to a README there should be at least one line of documentation for every
function longer then three lines of code.

I like documentation-driven design - when I'm to write a long and complex
routine I always write in pseudo-code-comments what I am to do.

This pseudo code usually ends up as the documentation of the routine (little
grammar/language update might be needed)

------
bosky101
readme driven development should be compared to mock driven web design

------
vcr2
It would be nice, if we dont consider the fact that nobody reads README at
all.

"A perfect implementation of the wrong specification is worthless."

The point of BDD is exactly this: bring specification to the scene, give it a
first class citizen status, it becomes a live entity in the system, more
influential than before. I don't believe Readme or any other document can be
as influential as a Cucumber feature, for instance.

~~~
adamv
From a "using stuff off of GitHub" perspective, the README file is front and
center when you look at a project.

~~~
preston
Yep. _Especially_ when using GitHub regularly, I'd argue that the README is
the most important documentation file of the entire repository.

