How can I apply Readme Driven Development to an ongoing project?

Question

I'm assigned to a project where the goal is to update an existing software. This software was developed in a totally ad hoc manner, which means that any documentation generated is outdated, confused and just plain useless. I do not want to retroactivelly produce all the missing artifacts, since this would just be a waste of time. The code base is ugly, and really need some serious refactoring, but this is another story.

What I want is to apply Readme Driven Development to guide this project. So, basically, I want to write a Readme, which will document every change meaningful at the user level. The problem is, I have no idea about how to structure this document. For me, it's pretty clear that it should have a different layout than the traditional Readme. I really want to document changes, and not the current state of affairs.

Any ideas?

Answer 1

The author of the blog post was trying to make a point about how the Agile Manifesto emphasizes "working software over comprehensive documentation", and that when you do this, you risk losing the information about how software is supposed to work.

What's needed, whether it's Waterfall, Rational Rose, Agile, or some other SDLCM, is a "statement of purpose". It is some textual description of what is to be done, and why, at a detail level fine enough in the right areas that a developer can take this description into the team room as his "requirements", and produce correctly-behaving software as a result of his development efforts, guided by whatever methodology he or his team or managers see fit to follow.

In Waterfall, this is the Requirements Document. It's all defined, in detail, up front, before development begins, and if it changes while the project is out for development, development stops and the team reverts to the "design" phase.

In UML/Rational Rose, this is a "use case narrative". It describes what the "actor" (a person in a specific business role, or an external automaton such as another program) will do that should trigger some action, and what will happen within the system as a result of this action.

In Agile, this is a "user story", the exact form of which can differ depending on the exact flavor of Agile, but the two I've seen are similar to a UML "use case narrative" and a slightly different approach: "As a... I want... so that...". Similar to a use case in that the actor and the basic action are mentioned, but the addition is an integration of the business need into the context of the story, so when designing the solution, the development team can keep the business need in mind.

None of these is a "readme", and frankly I wouldn't want to read a readme that was written in the way the blogger suggests; it will be long, it will be ordered only according to the order in which the developer added the requested features, and it will be written by a developer, who will have his own perspective on what he's adding or changing and why that may not coincide with the perspective a user would have.

Answer 2

While I agree with the author's assertion that you should write out a general description of what your program should accomplish before writing the first line of code or the first unit test, that's just common-sense. Figuring out what you want to do first before you actually do it is an essential component of any human endeavor.

Readme's are not structured at all; they are just text files, with no standard for creating them. Further, authors use their readme file for different things; as a Version Description Document, an errata, things you need to know before you begin, etc.

In short, Readme-Driven Development is not a software design methodology; it is merely a clever mnemonic device the author invented to make a point. If you're looking for an actual methodology, TDD coupled with a feature list and some design prototypes will do the job better.

Answer 3

My advice is to avoid the readme's approach.

You are recreating and worsening the problem for the future.

Te readme's will, over time, be maintained by different developers with different styles. Eventually there will be differences between the readme's and the implementation and that will be really annoying.

I can only give this advice - which I know will probably seem (and may well be) very impractical for all the change it seems to imply, but the thing is I think it is the RIGHT thing to do and in the end that's better.

So what I would do is:

1) focus on getting those tests written or upgraded first. Your regression test suites are key to further changes. They are the core of the documentation you seek.

2) Refactor the code making sure the tests pass and coverage the needed case.