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 Sat, 02 Jun 2012 01:10:23 GMT

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

miles zarathustra commented on HTTPCLIENT-1201:

Not meaning to flame, but my comment reflected the sheer pain and aggravation of trying to
figure out how to do a simple task.  You can object to my expressing it, but the pain was
real, and from comments I see on the web I'm not alone.

OK, I see the posting example (fragment) now.  Maybe the title could be more helpful?  When
I want to post a form, I do not think "hey, I want to produce entity content!"  

A title like "How to POST form content" might be a more useful title to someone(like me) trying
to find that section.  Think of questions someone might be trying to answer by reading the
documentation, not the nuts and bolts of the implementation. 

As a user, I am trying to get something done in a timely manner.  I do not want to spend hours
sifting through information I will not be using again.  The key information should be at the
top, and more detailed explanation pertaining to it following close by.  Headings should help
me find the answer I'm looking for.

Effective help should address ALL learning styles, not just one.  I still think the 'quick
start' should be easier to find.

The 'tutorial' seems to be written from an implementor's viewpoint, not from the viewpoint
of someone trying to use the API.  True, there is a lot of good information in there, but
as a user (developer), I find the tone of it off-putting.

As for "inappropriate phrases," I could have just said "hey, I figured out what I need to
know, screw everyone else," but I thought it might improve life for the next person to come
along if I took the time to suggest a way to make the documentation more useful.  And yes,
I might do it in a colorful manner, but that's my prerogative.


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