hc-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Eric Hubert (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (HTTPCLIENT-1201) provide basic documentation in an obvious place
Date Sat, 02 Jun 2012 13:07:24 GMT

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

Eric Hubert commented on HTTPCLIENT-1201:
-----------------------------------------

Miles, I basically also do not want to misuse the issue tracker for discussions - those could
be easily moved to the dev mailing list if there is a demand. So back to supporting you in
helping to improve the current documentation in the sense of your issue...

Without knowing this project well it took me a few seconds to locate the maven site at its
default place:
https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/src/site/apt/index.apt

As you also seem to be interested to improve the existing tutorial, here you go for the fundamentals
chapter:
https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/src/docbkx/fundamentals.xml

Better ask one of the team members whether it would be best to provide patches against trunk
or the latest release tag though (in that case replace trunk with tags/4.2) or check if there
is a delta.My assumption would be that there should be no difference at this stage.

Thinking about documentation improvement I would also add a suggestion. I don't know much
about the docbkx maven plugin, but I guess it is also possible to also output a single html
page comparable to the pdf document, without much effort. At least it should be possible to
define a single page xml using entity includes of all chapter xml files plus a single page
xsl, or? 

It would be cool to offer the end user with three options single page html in addtion to multipage
html and pdf as of now. I have seen this at http://www.jboss.org/resteasy/docs for example
and did like this page and the experience very much.

Rationale: 
If you encounter a lazy user not like the teaching tutorial approach rather focussed on grabbing
and extracting source code snippets out of it, a single page html is optimal for searching,
e.g. in the case of the issue reporter he could still easily find the information he was looking
for via Strg+F entering "POST" and at least the fifth hit would have shown him what he was
looking for. Of course the same is already possible with the PDF, but I think there is a certain
resistance of having to download a file and use a certain reader...

If there is interest and no one did this before, I could look into it and provide a patch.
I'm asking before as there might be a little maintenance overhead involved and it will not
be me having this overhead. ;-)

@Miles: A few last thoughts regarding documentation and quickstart requirements. I think one
should never forget that http client really has a large feature set and there are dozens of
use cases an end user can address with this library. 
Naturally every end user only thinks of his particular use case (being it only one of multiple
basic http operations like POST or PUT or something more complex) as the ONLY ONE and may
expect an immediate quickstart entry point. In my mind this is non-trivial to address.
Maybe a more complete example list of the most common use cases ordered by the likelyhood
of end user demand would be a very good thing. This could also integrate your requested POST
example.
On the other hand it is also all about maintenance effort. Examples as well as documentation
must be concise and always correct (otherwise they are hurting more than they are helping).
Any code change visible to end users needs to be properly updated in all available samples.
Rarely users (developers) contributing features provide proper source code (including java
doc and unit tests) plus external documentation and samples and almost never they will be
the ones who will keep maintaining their contribution over the years. So I for one show great
respect to the ones who do all this in their free time.
                
> 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


Mime
View raw message