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 Fri, 01 Jun 2012 19:55:25 GMT

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

miles zarathustra commented on HTTPCLIENT-1201:

Sorry to belabor this, but moving the WIKI link to the Documentation section on the LHS would
help a lot.  (on this page):


Again, a DIRECT link to the basic example from the WIKI (or a copy thereof, if you don't like
putting the external link there) would be extremely helpful, BOTH in the LHS Documentation
section, and the main "documentation" section.  At the top.

I would recommend for the Documentation section on the right, a bulleted list of links in
the logical order that a first-timer might want to read it, along with a helpful descriptive
paragraph following each one.  I.e. start with the basic knowledge, THEN put the sections
that assume the knowledge of the basics. 

List the exact same links without the paragraphs on the LHS, in the exact same order so they're
consistent.  It may seem stupid, but consistency is important for clarity.  Please remember,
beginners need to use this too.

You may not realize it since you're so knowledgeable about the project, but google searches
turn up much more about httpclient 3, and many of them do not indicate that it's obsolete.
 So a lot of the examples one finds by searching do not work with httpclient 4.  They fail
without error, which is quite frustrating.

In fact, when I search for httpclient, google takes me to the home page of httpclient 3. 
At least that site DOES tell me it's obsolete!

Since the WIKI is not listed in the Documentation section, it took me a while to find and
realize it was the only place to find the information I needed.  For a beginner, the chaotic
structure of the documentation is a painful experience.  

It seems to me worth the effort to fix it.

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