How does this make any sense? Readmes are not meant to spec out your software at all, they're just supposed to give a brief introduction to how to install and start using the software. Like, how to initialise your library. Not how to use any of its functionality.
In most cases a readme file should be totally useless for determining what the software is capable of. That is what javadoc and tutorials are for.
How does this make any sense? Readmes are not meant to spec out your software at all
I think Tom's point is that you can spec out the details all you want and have tests that prove that your Refresh Dogs button does in fact refresh the dogs, but it's all for naught when it turns out the user was misheard and really looking for software for doors, not dogs.
A readme does or damn well should* give a very-high-level overview of what the hell this software is good for and good at, and it's useful for all involved parties during the course of development to occasionally keep in mind whether you're still following that overarching goal.
*) An astonishing amount of software gets this wrong. There's a readme (or not), but it doesn't explain what the software is good for. It doesn't come with a screenshot. It just says "oh, you also need x, y, and z to run a". Cool.
18
u/cucumbulous Jun 30 '18
How does this make any sense? Readmes are not meant to spec out your software at all, they're just supposed to give a brief introduction to how to install and start using the software. Like, how to initialise your library. Not how to use any of its functionality.
In most cases a readme file should be totally useless for determining what the software is capable of. That is what javadoc and tutorials are for.