Seems that mojombo practices what he preaches. First commit by mojombo (from march 29, 2010) of Github's Gollum wiki reads "readme driven development!"
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.
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...) 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.
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.
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.
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.
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.
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.
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.
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.
Reminds me of another gripe I have: Rails puts a README in the generated app directory. It's not worth it IMO. I wish they'd get rid of it or change the name, or failing that, GitHub would detect unmodified Rails READMEs and screen them out.
By the way, I think abandoned README-only repos are a side effect of something useful - attempting to start new projects on the right foot. I think starting projects like this probably does more good than harm, overall. :)
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...
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.
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.
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!
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.)
He mentioned in passing that writing a typical README requires just the right amount of planning upfront
"just the right amount of planning upfront" is exactly what Scrum should do. It's not full-circle at all, it's another approach to current good practices.
You could pretty well describe the software methodologies of the last twenty years as being over-generalizations of basically good ideas. Once a given reasonable idea has pushed beyond its usefulness, the opposite good idea appears and ... is pushed beyond its usefulness.
Tossing out understanding and just having tests and code can easily result in disaster in many cases (compilers, sudoku solvers, etc) while over-designing can result in the opposite disaster in other cases.
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.
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.
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.
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.
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?
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.
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.
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.
- 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
You are correct. So I suppose I should alter my previous post by saying that it is a good way to go iff you are also willing to be diligent in your updates to keep the documentation as current as possible.
That's a holdover from the good old days when you had to search through 3" of fanfold paper for your function, they become a bit easier to spot like that.
Whoa sorry, I wouldn't have deleted the comment if I had seen your response. I had decided that I was just grumbling and it didn't add anything to the conversation.
More or less, I had said that I hate that kind of coding convention, because while it's well intentioned, in reality it mostly adds an incentive against extracting repetitive code out into new functions. Also, I'm tired of seeing comments that say:
because somebody's shortsighted coding conventions required it - they tend to camouflage comments that actually matter. If you need big headlines to find where your functions start, get a better editor. (But I'm sure that was less applicable a decade or two ago.)
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.
When I'm researching new tools/libraries, the first thing I read is the README. If it's worthless, then it's a fair bet the tool/library is, as well, and I won't be using it by choice. After that, I look at the official documentation. If all it has is auto-generated API documentation, that's another strike against it. Then I look at the API documentation. The tests are somewhere way in the back after all of this.
The point is that writing one is valuable -- it tests your ability to articulate an understanding of your own work from a high level, which is not always obvious when our focus is frequently at the code level.
show me a christian that grok'd the entire bible before calling themselves a christian, and i'll show you a developer who reads the entire behavioral specification of a library before using it.
your idea works for libraries that are small, it's appalling for libraries of any significant size.
the point of a readme is to provide a useful summary that is quick to start using for the critical path use cases.
if you look at a web framework in a language you don't know as an example, and try to find the introductory use cases in the tests, this should give you some idea of what you're suggesting.
http://github.com/github/gollum/commit/c7875704971be998a5399...