On mar, mag 26, 2015 at 08:28:44 +0200, Daniel Stenberg wrote:
> Hi all!
>
> My document with all details and analyses of the curl user poll 2015 is now
> available. It shows details of all the questions, most of them with a
> comparison with last year’s survey. The write-ins are also full of good
> advice, wisdom and some signs of ignorance or unawareness.
>
> Download the PDF from here:
>
> http://daniel.haxx.se/media/curl%20user%20poll%202015%20analysis.pdf
>
> Enjoy!

So, I just finished reading it, and here are some thoughts:

> bad documentation / users don't know about supported features

It was mentioned several times that the documentation is a bit unaccessible,
with its huge wall of options (for both libcurl and curl). I think having a
more use-case oriented documentation would help here, something like MANUAL or
TheArtOfHttpScripting but, well, better (e.g. with links to the documentation
of the options described, covering more features, with examples for both curl
and libcurl, i.e. something more interactive than a simple text file). This
would also help in educating users on what features are supported, if this
documentation gets properly publicized (see below).

As far as the documentation for the options themselves is concerned (again, both
curl and libcurl), it would help splitting them into different categories (e.g.
HTTP, SSL, FTP, ..., output, proxy, ...). Examples:
http://mpv.io/manual/master/#options
http://gnutls.org/manual/gnutls.html

Another thing somewhat related (but not really) is that IMO, actually modifying
the documentation is a bit of a pain, mostly due to the use of whatever roff
dialect is used (but it could be just me). A lot of more "modern" options exist
see e.g. the mpv example above or something like http://sphinx-doc.org/.

> bad website

Leaving the retro look aside, I do agree that the website is confusing. The Docs
and Development pages pages have tons of links that can be a bit overwhelming.
A better one could have some sort of getting started section in the homepage
with some of the more common examples of usage (and a link to the documentation
above).

Examples: http://ffmpeg.org/, http://docs.python-requests.org/en/latest/

> bad API

There are several things that IMO could be improved here, starting from having
a more consistent naming scheme for options (some options seem to follow some
kind of naming scheme like CURLOPT_<protocol>_<name>, while others ignore that).

More generally, while the libcurl API is very flexible, I think it could also
target more specific and more common use cases. Stuff like "retrieve this URL
and put it into a buffer" instead of having to deal with the callback thing,
adding and parsing headers instead of having to deal with slists and the header
callback, etc...

I also think that having actual functions (with proper types) instead of just
one generic setopt() would help things as well (but it may just be me...).

There are other things as well, but I think that's eanough for now.

So, any thought?

Cheers

-------------------------------------------------------------------
List admin: http://cool.haxx.se/list/listinfo/curl-library
Etiquette: http://curl.haxx.se/mail/etiquette.html