serverco,
Thanks for your clarifications.
“one issue here is that saying ‘the documentation isn’t good enough’ (which no one is disagreeing with) doesn’t help.”
Not so; it does help. If no one points out a big problem, the problem will simply remain. The evidence is that no one working to develop LE has much interest in developing high-quality, clear easy-start documentation that will help the audience of LE to gain the enthusiasm to give it a try and become a convert. Appalbarry expressed this perfectly.
“If you have a specific issue, that you can’t understand how do do, because it’s not in the documentation, then please ask about that specific thing.”
No, that is not the best way to view either documentation or software. Applied to software, you are saying something like, “yes, we know the software is buggy, but until we have your set of specific bug reports we have no way to fix it. All the software works perfectly for me, so I can’t know what problems you are encountering.”
The point here is that if our solution is “free, automated, and open. Get Started”, then forcing visitors to have a bad experience on the Get Started page shoots ourself in the foot. Offering even an interactive chat panel on the Get Started page to hold the visitor’s hands cannot compensate for a bad experience with the initial documentation.
Compare with other ambitious projects like Angular, jQuery, Prezi, Weebly.com, Google AdWords, Python, and so many others that, whether complex or simple, work right away either full-scale or starting with easy examples, thanks to great documentation). We not only fall short, we fail.
Also, it is beyond the project’s resources to answer the thousands of questions we would have if our entire audience visited our site as we might secretly desire. Already, we have seen LE been more successful than anticipated. Do you really want us to be overwhelmed with interest and visits and become the next Internet news about a failed project? Please abandon this tired old advice. Yes, it is clear that you believe it, but belief is not enough; clarity, honesty, and courage are also useful (reference: the Emperor’s New Clothes, by Hans Christian Andersen).
“and also people understand then a specific point where the documentation needs to be clearer.”
Neither documentation nor software should be developed by fixing bugs. Fixing bugs is the last resort, and even that process should be done as early in the development as possible (reference: almost everyone who has written about the software development cycle).
If you don’t know how to write clear, simple, appealing, and adequate documentation, as you seem to be claiming, then we simply find someone else in the project who does. If no one does (which is possible, since this has been primarily an engineeering project), then we should hire an outside person with a good track record for doing the job. Documentation, like software development, requires unique skills.
“I appreciate what they are trying to do, and hence put some of my time aside to help others.”
And I thank you. I’m sorry to be so forceful here, but it’s an important area that has been neglected, and your latest post doesn’t seem to help. I have no intention to criticise any person on the project, and certainly not you (you have spent much time on this thread alone, which I appreciate). I try to focus my criticism on the issues.
“The documentation was good enough for me to obtain certificates, and also to write my own client for issuing certificates”
I am happy to hear of your success. I would be interested in knowing your training and experience and to compare it with the median training and experience of the potential audience for our technology. Nowhere on the LE website is a list of required training and experience specified, therefore it appears that our audience is anyone who runs a webserver. That includes people who use shared hosting (who are currently not served by the Get Started solution), anyone who runs a Windows webserver (who currently are not served by the Get Started solution, and are not served at all if they don’t want to install python and other doo dads that make Linux developers happy), and people who have no idea how certificates or command lines work, who are also not served by the Get Started solution as it is currently documented (and, perhaps, as it is implemented).
Our documentation does not present the expected training and experience required of our current technology, nor does it present any limits of that technology. It is just a cheerful, promising claim backed up by a documentation and technology that does not match the claim. LE is poised to fail as a result of its success.
“I don’t read the documentation in the same way as a new user.”
If you don’t have the ability to recognize poor documentation (defined as not matching the audience), that is fine. As a software developer you can be a great contributor. Just don’t get in the way of finding someone who can write great documentation, perhaps someone with technical writing experience. Feeling that you yourself must take on the responsibility to improve the documentation means taking on more responsibility than you can handle; that is not good for you or the project (reference: https://en.wikipedia.org/wiki/Peter_principle).
Each contributor should work within their limitations, and not force others to be “specific” in making problem reports when the basics have not yet been covered clearly or completely.
Again, I am trying hard not to criticize you, but your posting is getting very personal about how you read documentation and how you like your problem reports. It is fine to express your opinion, but please state it as opinion and not as The Required Way We Do Things, okay? (Oops, unless this is not really an open software project but you are actually the project manager and in charge of everything, in which case I humbly apologize for my inappropriate suggestions.)
