I agree with another commenter that this doesn't tell the entire story, but it tells almost all of it. Nowadays, I discover some new piece of software, visit the Documentation section of its website, and the first thing I see is `How to build SuperMung on the Whizzbang 47 using Mark Williams C'. I have no idea what SuperMung is for, how to use it, what errors I might make, and how to install it on Debian. Similarly, I go to the website for a new programming language, see some examples that give me little insight into what it is for, and find not even an incomplete language specification.
Proper documentation leads me by the hand, starting on what the software is for, what platforms it runs on, some examples of its use (including examples that show how it is useful for solving real-life problems), a thorough tutorial on how to use it, and finally a complete and properly indexed/searchable reference.
Back in the 1980s, I got myself in trouble: I promised a 100-page manual for a software system I had written, and I decided to do it in the then-new TeX. But this was before The TeXBook was published. So I learned TeX by reading the literate source for the code. The manual was duly ready on time, and served the literally thousands of students who relied on it for the next few years.
But when I finally got a copy of The TeXBook, I was astonished by how little I had actually known about using TeX. I had presumably been mostly using it to answer questions such as “why doesn't this work?”, and a lot of the overall principles had simply not been apparent to me. Once I had learned TeX properly, I learned a great deal about how it all worked by going back and reading the literate source. Knuth is a brilliant (if highly idiosyncratic) programmer.
My point here is to emphasize that when someone releases software, their job is not done unless people can learn to use it. That doesn't just mean completeness and accuracy, but a through-line, apparent to the reader, from learning what it does all the way to mastering it, along with the kind of reference information needed when using it.
Proper documentation leads me by the hand, starting on what the software is for, what platforms it runs on, some examples of its use (including examples that show how it is useful for solving real-life problems), a thorough tutorial on how to use it, and finally a complete and properly indexed/searchable reference.
Back in the 1980s, I got myself in trouble: I promised a 100-page manual for a software system I had written, and I decided to do it in the then-new TeX. But this was before The TeXBook was published. So I learned TeX by reading the literate source for the code. The manual was duly ready on time, and served the literally thousands of students who relied on it for the next few years.
But when I finally got a copy of The TeXBook, I was astonished by how little I had actually known about using TeX. I had presumably been mostly using it to answer questions such as “why doesn't this work?”, and a lot of the overall principles had simply not been apparent to me. Once I had learned TeX properly, I learned a great deal about how it all worked by going back and reading the literate source. Knuth is a brilliant (if highly idiosyncratic) programmer.
My point here is to emphasize that when someone releases software, their job is not done unless people can learn to use it. That doesn't just mean completeness and accuracy, but a through-line, apparent to the reader, from learning what it does all the way to mastering it, along with the kind of reference information needed when using it.