Every programmer wants to write better software, whether that means writing cleaner, faster code, sticking to best practices or documenting your work for long-term upkeep. But if your code doesn’t serve the needs of your users then it’s worthless, no matter how great it may be. So how do you make sure your beautiful code isn’t just an abstract work of art, but actually serves the end goal of making your users happy?

Tom Preston-Werner, the co-founder of Github, has some advice: write your README first.

That is, sit down and write out exactly what you want your software to do before you start writing any code. “Until you’ve written about your software, you have no idea what you’ll be coding,” Preston-Werner says.

Some developers may recall the days of the Waterfall model, a design and coding practice that advocated detailing all the minutiae of, well, everything. Today’s buzzword- systems like Agile Development are in many ways a deliberate attempt to move away from the complexities of the Waterfall Model.

Preston-Werner isn’t advocating a return to it. He carefully points out that the Waterfall model is overly complex, but “there must be some middle ground between reams of technical specifications and no specifications at all.”

That the middle ground is the good old README.TXT file. It’s typically much shorter than full-blown documentation driven development, but still forces you to go through an abbreviated, but very helpful part of development — making sure everyone, including you, is clear on what you’re trying to do.

Treat it like a mission statement: “[The README] document should stand on its own as a testament to your creativity and expressiveness. The README should be the single most important document in your codebase; writing it first is the proper thing to do,” writes Preston-Werner.

Wondering what constitutes a good README? Preston-Werner points to Gollum — a wiki built on top of Git — as a well-done example.

Not everyone is going to agree. There’s an interesting discussion about his post on Hacker News with a roughly fifty-fifty split. It’s a surprisingly civil discussion, free of dogma as well.

See Also:

• A Subversion User’s Guide to Mercurial Version Control
• Google Raises Your Coding Skills to a Higher Degree
• Code Optimizers Can Make View Source Useless