Am 16. Juni 2014 bei 16:01:14, Daniel Stenberg (daniel_at_haxx.se(mailto:daniel_at_haxx.se)) 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
Received on 2014-06-16