[
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: [email protected]
For additional commands, e-mail: [email protected]
