hc-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "miles zarathustra (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (HTTPCLIENT-1201) provide basic documentation in an obvious place
Date Thu, 28 Jun 2012 16:39:43 GMT

    [ https://issues.apache.org/jira/browse/HTTPCLIENT-1201?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13403203#comment-13403203

miles zarathustra commented on HTTPCLIENT-1201:


Your comment explains a lot.

So here's the thing: the entire point of an API like httpclient (and a "QUICK" start page)
is to 'abstract' away details which, most of the time, do not matter or can be dealt with
in a default manner.  That way, the developer is not forced to waste time thinking about minuscule
details of implementation and can be left to focus on the important part, namely what it is
they are trying to accomplish.  

In brief, it should be saving people effort, not creating greater effort.  It sounds like
your goal is to create greater effort.

Enough said.  I'm not going to debate this point.

What I would request is that you at least explain what you are doing on this 'quick start'
page.  Something to the effect of "the try/finally block is shown to illustrate the scope
of finalization, and in order for the code to compile you will need to think about how to
handle exceptions."

Since you seem to have strong feelings on the subject, it might be worth writing up something
on what it means to 'properly' handle exceptions, illustrating what you mean with code that
DOES compile, and link it to the documentation.

Publishing code that doesn't compile just annoys people, (me, anyway) and probably won't do
much to educate them.  It leaves me thinking "Can't this guy be bothered to write code that
at least compiles?"

I don't think that's what you are after.

  -= miles =-

> provide basic documentation in an obvious place
> -----------------------------------------------
>                 Key: HTTPCLIENT-1201
>                 URL: https://issues.apache.org/jira/browse/HTTPCLIENT-1201
>             Project: HttpComponents HttpClient
>          Issue Type: Improvement
>          Components: Documentation
>    Affects Versions: 4.2 Final
>            Reporter: miles zarathustra
>            Priority: Minor
>             Fix For: 4.2.1
>         Attachments: GetPostExample.java, site-1.patch, site.patch
> The only documentation obviously linked from the main HttpClient page is the "tutorial."
 This "tutorial" talks about a lot of esoteric arcane junk I don't care about, but gives no
clue on how to send parameters via a basic post.  For that, I have to go here: 
> http://wiki.apache.org/HttpComponents/QuickStart
> It's very difficult to find, and it's a lot easier to google examples that don't work.
 I wound up trying 4 different purported solutions before I found this one that works. If
you look around the web you'll notice that people generally find the httpclient documentation
frustrating.  I have colleagues who argue that it would be easier to just write the post logic
from scratch than figure out how the silly apache stuff works, and it's difficult for me to
contradict them.
> It would be SO easy to improve the situation by making links to already available examples
of the basic operations in an obvious place.
> The FAQ that explains some things about WHY the posts work in the totally non-intuitive
way that they do would be nice also.
> Thanks.

This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira


To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org

View raw message