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.
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.
Still, good stuff. Just leaves a few questions.
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.
(declarative programming for the rest of us!)
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. :)
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.
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.)
"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.
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.
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.
I can see its usefulness in documenting test 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.
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. :)
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.
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.
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
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?
I will be trying this on my next project!
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)
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:
* theFunctionName *
"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.
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.
Really could you see a developer reading the entire .net or java standard library test suite before using either Java or C#