
Readme-Driven Development (2010) - js2
http://tom.preston-werner.com/2010/08/23/readme-driven-development.html
======
jschwartzi
One of the senior engineers I worked with at my last job was very picky about
the difference between verification and validation activities. In testing,
most design engineers will focus very heavily on verification activities which
seek to answer the question "does what I built satisfy my design intent?" In
contrast, validation activities seek to answer the question "did I design and
build a thing that actually solves the problem?"

It's very important when you're building something that you answer both
questions in your test activities. So you might write your Readme for your new
project, and then as a validation activity before you build your project you
shop your Readme around to the target audience of the tool and ask them if the
tool sounds useful. You might also elicit feedback about how features could be
more useful, or if there are other features that could be added.

From your Readme and your initial validation, you start an initial
architecture of the system, laying out the pieces you think you'll need and
describing how they will interoperate in broad strokes. Other developers can
join you at this point, and knowing your architecture design and implement
specific pieces of the tool. All design work references the Readme as a
functional specification. And all of your verification activities verifies
that the design was implemented and that the implementation satisfies the
Readme.

As you're iterating and building new functionality, you integrate periodically
and perform validation and verification against integrated versions of your
system. And the verification tells you that you're following your Readme,
while the validation tells you that your users indeed find the tool that you
spec'ced useful.

The only real difference between Waterfall and Agile in this model is the
cycle time. Waterfall has a very long cycle time in the specify-design-
implement-test-validate cycle, whereas Agile has a very small cycle time. And
so the chunks of the system vary in scope as well.

~~~
sah2ed
So, essentially:

\- validation is checking that there exists at least an end user _who will
need_ what you are building;

\- verification is checking that what you have built so far _will meet or
continue to meet their needs_ and other end users similar to them.

------
wanghq
This is similar to Amazon's "working backwards" based product development.
Before writing the manual, they do another important writing - press release.
It's amazing to see they talked about this idea a decade ago and still use the
same approach to drive the development today.

[https://www.allthingsdistributed.com/2006/11/working_backwar...](https://www.allthingsdistributed.com/2006/11/working_backwards.html)

~~~
mafro
The writing of user manuals before development sounds an awful lot like
waterfall :)

~~~
Crespyl
It's really not a bad way to build something when you already know _for
certain_ exactly what you need to build.

~~~
ljw1001
It could be a good way to build something when you don't know what you're
building. Writing a user manual is cheaper than coding, but may force you to
get pretty explicit about what the user experience will be like.

------
svat
Incidentally, Donald Knuth (whose literate programming idea has never quite
taken off, mostly because of a lack of good tools and examples IMO) was doing
this even before coming up with the idea of literate programming. He wrote
basically a TeX manual (or one could at least call it a design doc),
completely describing what TeX "does" (he wrote it in the present tense), how
it works, etc., months before writing a single line of code. (See TEXDR.AFT
and TEX.ONE, published in _Digital Typography_.)

Even later, when TeX completely changed between its earlier version (the one
written in SAIL, aka TeX78) and the current version (written in WEB, aka
TeX82), the program has completely changed, but the manual he wrote for TeX78
is still very similar to the latest version of _The TeXBook_. Since declaring
TeX "done", he's generally been willing to make only changes that don't change
_The TeXbook_ much.

~~~
User23
The tools are great if you’re Don Knuth!

Yeah I never got in gear with CWEB either.

~~~
taeric
I get the impression that is supposed to be somewhat derisive. That said, I
think the tools are more usable than people give them credit. They are just
slower to get started with.

In particular, I've been picking up The Stanford Graphbase book recently and
finding that after I have gotten used to reading more parts, the programs are
getting a bit easier to understand. In ways that don't litter my mental model
with tons of surface complexity.

What I mean by that is that if you look at the javadoc or "function/method"
base of a complete system, it is easy to lose site of the whole. Granted,
getting started with the larger texts of some other documents can have similar
problems in reverse. It is hard to really get a handle on where in the system
you are to start.

~~~
User23
You got almost the exact wrong impression. You're correct that my comment was
a bit derisive, but the derision was aimed at myself. Don Knuth is a giant in
our field.

Also thanks for the reference.

~~~
taeric
My apologies on reading it wrong.

If you pick up a copy, have fun reading it! :)

I also recommend reading some of the programs he has posted to his site. I
have not picked up the rendering book done in a literate style. Is on my
ambitions list.

~~~
jacobolus
For anyone who wants to try writing (Javascript) code in a literate style,
give Observable notebooks a shot,
[https://beta.observablehq.com](https://beta.observablehq.com)

------
nsgoetz
I took an OS class in college where either a TA or professor would read every
line of C code in the OS you turned in. They required every function to have a
doxygen style doctrings. It was also a partner based course. Writing those
docstrings before implementing the functions not only helped them be more
useful, but also helped my partner and I coordinate on features/interfaces
before they were done. I think documentation in general is highly underrated.

~~~
wck0
I forget where I saw this, but it struck me as very good advice: Don't
document your code, code your documentation.

~~~
cbcoutinho
Sounds like literate programming, popularized by Donald Knuth

------
kuon
I always write a README first for my projects, even when I am working alone on
it. I also always create a Makefile, even if the project doesn't use make at
all, I know I can enter any of my project and hit make help to know what it
is, and if I am browsing on gitlab/github, I can read the README.

When creating the project, I put in the README a general description, project
goals, a TODO list, contact info (email...), requirements (like node,
ruby...). Often, I write the readme, and leave the project a few hours to a
few days, when coming back, I read the readme and it should "enlight" me.

------
devj
The purpose of documentation is to keep all the stakeholders on the same page.
However, each stakeholder may write the document in his/her own perspective.
This leads to further confusion and eventually makes people hate
documentation. Thus, making the whole exercise ineffective.

For example, the same product will be paraphrased in different ways by your
customer, your marketing dept, your business team, your tech team, etc.

On the contrary, Amazon had been quite successful with their 'Working
Backwards' model of development because they always document from the
customer's perspective. This I believe is the right approach.

I have created my own model on the above premise to make SaaS product
development more effective. You can read more about it here -
[https://medium.com/jugaads/the-stoics-cube-for-saas-
product-...](https://medium.com/jugaads/the-stoics-cube-for-saas-product-
development-6e666842bf9e)

------
Razengan
While not exactly what the article suggests, writing the documentation for my
open-source game engine [0] actually helped me improve the API itself:

When I was writing out the examples and trying to see them through the eyes of
a new reader, I noticed that some simple tasks took too many lines of code,
and would be a turn-off to potential users of the engine.

I felt like I should get this down to N lines, and that led me to revising the
API until it could be illustrated in "prettier" examples (though there's still
some work to be done.)

So yes, writing out the documentation and looking at it while "away" from the
project (e.g. reading it on another device, an iPad in bed in my case,
rendered on GitHub etc.) can definitely help you improve other parts of the
project.

[0]
[https://github.com/invadingoctopus/octopuskit](https://github.com/invadingoctopus/octopuskit)

------
tmvnty
My role at our agency recently has been implementing a data layer for one of
our clients and I found our current documentation combo of Google Doc/Sheet so
frustrating. The times I find things to be inconsistent between pages and the
lack of examples really pushes back my productivities on the project, and I
can see the lack of good documentations will cause many troubles down the
road. I am almost tempted to stop the project for the moment and recommend to
my manager that we should revise the documentation workflows first before any
kind of implementations. My only struggle is to find any good
software/examples that can help me convince the manager that this is worth the
time and a good practice to carry out throughout the company

------
valw
This makes me think of Rich Hickey's Hammock Driven Development:
[https://www.youtube.com/watch?v=f84n5oFoZBc](https://www.youtube.com/watch?v=f84n5oFoZBc)

\- "Stay away from the computer" \- Start by asking: "what is the problem?"

------
dang
Discussed at the time:
[https://news.ycombinator.com/item?id=1627246](https://news.ycombinator.com/item?id=1627246).

------
Walkman
This is how Flask actually started. Armin wrote an April fool's joke but had
no code (at least not much) at that point, but nobody looked the code! They
just liked the concept and the documentation, so he had to implement it
afterwards :D

------
awinder
I just got through [https://www.amazon.com/Specification-Example-Successful-
Deli...](https://www.amazon.com/Specification-Example-Successful-Deliver-
Software/dp/1617290084) which pitches a common structure (Given-When-Then) for
describing behaviors and getting them out of your ticketing systems, which are
not designed for knowledge explanation long-term, but are more for describing
active work in short term.

BDD is almost a poisoned term at this point because it’s become associated
with tooling and opinionated holistic processes. But if you think of
Specification by Example as readmes with a Given-When-Then structuring, then
you have a strategy (document before writing) combined with a language
definition to assure your strategy is executed at the right level of detail.
Which solves the entangled problem of what do I do first (document) with what
level of detail (enough to describe all the input behaviors to whatever I’m
working on)

~~~
yojex
This is what Ruby/Cucumber tests use to define scenarios. It's called Gherkin.

~~~
awinder
right the problem is cucumber and gherkin lead to people trying to be very
smart and then tests become some ridiculous NLP problem. The value is the
readme file over a ticket, and language definition, not the gymnastics of
tying human language to executable test file.

------
alexgvozden
I see many people see this as backwards and top to bottom approach while I
consider it utmost bottom to top approach

in all the teams I worked most successful were ones that insisted on writing
wiki / readme pages for each feature and task...

why?

1) project manager (person knowing why we're building) has to do fair amount
of explaining to the developer 2) it's easy to verify that developer
understands what he/she needs to develop 3) everyone else in the team can
easily update themselves

my template was something like this

1) what has to be built 2) for whom - who is the typical user and scenario 3)
who will built it and which branch on git 4) what app parts will be changed 5)
any information related to deployment (database changes and similar)

doing it upfront meant a lot to the team, discussions and clarity... I would
just call this more Wiki development then readme :)

------
amelius
The most important aspect of software development is getting the requirements
right. I suppose this is where Readmes can help. However, I'm astonished that
many existing projects don't even document their underlying requirements
properly!

~~~
jopsen
Yeah, even if agile/iterative processes tells us we can't get the requirements
right the first time, that's not an excuse for not making a design.

I have seen many engineers write libraries without first having a clue how
does using the library would look.

------
maxxxxx
I wish I was a better and quicker writer. I am pretty good at designing things
and coding them but it's really hard for me to put the design on paper. Takes
me forever. I know other people who are really good at this and it's an
invaluable skill especially if you have a lead role.

------
franciscop
I totally agree! Especially for highly experimental features/libraries. I am
trying to finish a small new library today, and I'm basically following the
docs I wrote a week ago:
[https://github.com/franciscop/premonition](https://github.com/franciscop/premonition)

Code examples are very important in these situations.

The main issue I've found is that some times I like the docs I wrote, but I
don't do the implementation and feel like I wasted my time by documenting too
much. These times it might be because it was just a thought experiment, a wild
idea tat I had to write down or I just have other priorities.

------
tmaly
I am still trying to find a good balance for requirements format. I have
looked at Gherkin in a few books on specifications. The Microsoft press book
on software requirements lists every possible way to represent requirements. I
am working through the book Telling Stories requirements book by Ben Rinzler.
I still have not found anything ideal that would be easy enough to teach to a
business side that has no training on writing requirements and still provide
enough detail to the technical side. I am getting close to settling on some
form of diagram, user story statements, and use cases with Gherkin.

~~~
clintonb
What's wrong with English, literal sentences and paragraphs, or a few bullet
points? If you can write the readme or user-docs, you have written a
significant amount of your requirements. If you can add the various edge
cases, you've probably written about 99% of your requirements.

------
dfabulich
Moderators, add "2010" to the title?

------
wmccullough
>“but it’s all irrelevant unless the software meets the needs of those using
it”

I’m not trying to be a jerk here, but TDD does just that. I tried to read the
rest of this, but the logical fallacies are strong with this one.

------
rhizome
_The Mythical Man Month_ has this as one of its big things: the documentation
is the spec.

------
tzhenghao
On a higher level, this reminds me of Charlie Munger's Inversion mental
framework, best described here in a Farnam Street post [0]. A TLDR is to not
just think of all things needed to achieve X, but which that could make us NOT
achieve X.

[0] - [https://fs.blog/2013/10/inversion/](https://fs.blog/2013/10/inversion/)

