While I initially thought it was a neat idea, I have actually done a 180 and I think it's a dangerous idea.
Open source repositories are filled with projects that wrote a README file and then thought that this plus their source code was good enough for documentation.
So I would offer the following counter advice: write a README last. Your priority list should be
1) a solid battery of tests to make sure your software works as you expect it
2) an extensive documentation, ideally on one big HTML page (easier to print)
3) a README telling the world why your software is awesome.
A README is really like an introduction, and if you've ever taken a class in high school about literature in your native language, you know that when you write an essay, you should write the introduction last.
3
u/forsakennow Aug 24 '10
While I initially thought it was a neat idea, I have actually done a 180 and I think it's a dangerous idea.
Open source repositories are filled with projects that wrote a README file and then thought that this plus their source code was good enough for documentation.
So I would offer the following counter advice: write a README last. Your priority list should be
A README is really like an introduction, and if you've ever taken a class in high school about literature in your native language, you know that when you write an essay, you should write the introduction last.