On Tue, 26 May 2015, Alessandro Ghedini wrote:

Thanks for diving into this Alessandro!

>> 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).

Yeps. Basically the same critique as last year. I must say I do love how
direct people are in these polls though. The fact that our documentation
leaves a lot to be desired is without doubts, but at the same time we have a
lot of good documentation already.

We did split up libcurl options into hundreds of new man pages as a direct
result of last year's survey results, but then we didn't get much further.

There's also https://github.com/bagder/curl/pull/252 which attents to change
the --help output to become more readable.

Clearly we need to continue improving the docs situation.

> 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).

Yes, that'd be great. But that sort of documentation is also harder to write
than mere reference documentation and as we can see none of those documents
you mention are very well maintained and both suffer from being slightly out
of data (missing lots of more recent options).

> 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, ...).

The curl_easy_setopt man/web page is already split up in different categories.

The curl.1 man page should really get the options into sub categories as well.

I've also considered splitting it up on the web site with a separate
individual page for each command line option. I think it'll help us write more
about each option. But I've not managed to make it happen and curl.1 would
probably still need to be a single unified man page.

I never quite decided what the best way or look would be for that...

> 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/.

I'm not against changing to another source format as long as it can generate
good man pages as well as good web pages. I would guess that we would need to
make some sort of conversion script unless there already is one from the
current to the new format so that we won't have to do too much manual editing.

For me personally the format of the docs has never been an obstacle. One or
another syntax doesn't bother me.

sphinx-doc looks good. Are there other alternatives we should consider?

>> bad website
>
> Leaving the retro look aside

The retro look is not intended. Just the result of my inabilities to make a
good looking site.

I've tried to ask for help a few times over the years, but whenever people
hear "help me make the web site better" web designers go wild and want to
replace everything while I would prefer to just get new layout / style
suggestions/mockups independent of underlying technology. I like that huge
portions of the web site is populated by converted docs from the source tree
as it makes it easier to keep stuff in sync.

And I rather we stick retro and "ugly" than giving up contents and
functionality.

> 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).

Yes, most likely. I think the web site suffers from that it has been made and
is being maintained mostly by me alone.

I would be happy to discuss specifics of what to do where to make the site
easier to navigate and other improvements. Sub sections?

> bad API

We must not forget that while there are users who have this opinion, there are
also users with the opposite opinion. Over 20% of the users this year actually
marked "libcurl API" as one of the best areas in the project, only about 5%
considered it one of the worst parts.

> 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).

If we would restart the project now, we could indeed. But now? It seems weird
to consider renaming options just for the sake of consistency since we'd
introduce a huge documentation need and a need to re-educate a very large
community. I'd say the naming boat has sailed already. We'd do more harm than
good trying something like that now.

> 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"

Originally, and I guess to some degree still, I expected that people who'd
like more higher level APIs like you describe here would simply build that on
top of the existing libcurl API. We would provide the low level foundation for
someone else's more easy-to-use and easy-to-learn API.

Of course, such a higher level API library could be made by us too without it
having to be part of the libcurl core.

> 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...).

I would not use varargs this way if I would make libcurl from start today. But
I also don't see us introducing a completely new API just because of that
reason. This also, could be at least experimented with as a layer on top of
libcurl.

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