RDD

I found an excellent piece by one of the founders of GitHub talking about Readme Driven Development.

It's an interesting take on "agile" and "test-driven development" methodologies; as a response to the waterfall methods they were great.  But documentation accompanying them can often leave much to be desired.  That's certainly the case with our "agile" projects at work.  The software's done, the code is commented, and people are ready to move on.

Preston-Werner makes a good case for getting the Readme down.  The file shouldn't be long and doesn't need a lot of detail, but it helps you think about the bigger picture first.  It organizes your thoughts.  Because of it, you have a better idea of what to focus on first, and how pieces of the program fit together.

His other comment about getting other people up and going on the project without having seen your code is valuable, too.  I'm trying to be very diligent on getting any kind of design decisions or discussions into the project's Trac wiki for anything new that we do for this exact reason.  When it's there, in writing, it's far easier to remember what was agreed on, what direction we should take, and offers a springboard for new discussions.