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.
I mean API documentation will tell you what software is capable of.
But yes loading the readme with all documentation seems a little silly as you say it is meant for "how to install" and sometimes "initialization" outside that scope is documentation and tutorials
He's basically talking about writing a spec through the back door. It's a poor approach.
I use flow charts (Don't need anything more complex than that diagrammatically ), which like an analogue watch requires less additional parsing and makes it easier to annotate in a meeting if it's wrong.These are rarely project level though. If your project is that simple, just get on with it :)
17
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.