Am 16. Juni 2014 bei 16:01:14, Daniel Stenberg ([email protected](mailto:[email protected])) schrieb: > On Sun, 15 Jun 2014, Michael Osipov wrote: > > > For instance, someone contributes code and docs and never reviews it again. > > > > RFCs change, or get introduced, wording is bad or simply too much text or > > even worse it is not written/implemented the way it should be. For the > > spots > > I do use curl at work, would need an improvement/unification/rework. > > Yeah, I assume there will always be areas of the documentation that are > lagging behind. I don't see how it can work any other way. We depend entirely > > on users who use features and who find problems to submit fixes and updates. > > If that is what people mean with the docs being the worst part of curl, then > I'd be pretty content with it still. :-) > > -- > > / daniel.haxx.se > ------------------------------------------------------------------- > List admin: http://cool.haxx.se/list/listinfo/curl-library > Etiquette: http://curl.haxx.se/mail/etiquette.html
Hi, I voted for the docs as "worst part" of (lib)curl, because everything else is really great in my opinion. So I’d like to share some thoughts about docs: TL/DR: Add (developer-)guides. Better structure/modularization of docs and help texts to not overwhelm beginners but still point to the advanced details for advanced users below. 1) The libcurl docs are very good as a reference, but not so much for learning how or when to use libcurl. Guides would be great. Example project: Rails (http://guides.rubyonrails.org) (Showcases in tutorial-style for the most important use cases, something between reference, examples and a tutorial) I’d also restructure the docs website: Guides (with subsections) should be an important category besides the API reference, the examples and the FAQ. 2) If a beginner calls curl -—help, he is overwhelmed by many features. Maybe we could separate the help text into sections for each use case: -O, -L, -k, etc. for using curl as an alternative to wget. Then all options for using curl as a HTTP swiss army knife with -G, -F, -d, then FTP-related options and so on. Maybe the FTP help could even be kept out of —-help and put into something like —-help-ftp, etc. ? There are of course options applicable to multiple use cases, I am not sure how to deal with them. Separate section? The overall effect should be: User calls curl —-help, quickly grasps the sections/use cases, finds the option he needs out of 10-20 lines instead of having to visually parse over 150 lines of text. What do you think? Best regards, Clemens ------------------------------------------------------------------- List admin: http://cool.haxx.se/list/listinfo/curl-library Etiquette: http://curl.haxx.se/mail/etiquette.html
