[jira] [Commented] (FLUME-1987) Improving Documentation for Apache Flume

["Erik Bertrand (JIRA)" <ji...@apache.org>]

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

Erik Bertrand commented on FLUME-1987:
--------------------------------------

My feedback:

- I find the [jQuery documentation|http://api.jquery.com] to be well-organized, as well as attractive
- Comments to pretty much any documentation page, or at least the "reference" documentation, is essential; this is what makes the PHP documentation particularly useful
- That said, infusing "real-world" use cases into the documentation -- even the reference pages -- would be very useful; perhaps simply through an "Examples" section
- fwiw, I did have trouble find the right Flume documentation as I was getting into using the product, finding both the main and the Confluence versions; it was difficult to know which was "bible", or at least the latest
- I'd suggest a section that lists version history with changelog; perhaps it could simply be linked to

This is an excellent project, well worth the effort!  Thank you for spearheading it.
                
> Improving Documentation for Apache Flume
> ----------------------------------------
>
>                 Key: FLUME-1987
>                 URL: https://issues.apache.org/jira/browse/FLUME-1987
>             Project: Flume
>          Issue Type: Brainstorming
>          Components: Docs, Web
>    Affects Versions: v1.0.0, v1.2.0, v1.4.0, v1.3.1
>            Reporter: Israel Ekpo
>            Assignee: Israel Ekpo
>   Original Estimate: 672h
>  Remaining Estimate: 672h
>
> Hello Everyone,
> I have been giving this a great deal of thought over the last 3 weeks.
> I would really appreciate feedback on how we should proceed on this from users, developers (committers), and project management perspectives.
> It would really be nice for the documentation for the project to be moved from git into the wiki and organized in a manner that makes it easy to locate information on features, components, processes etc.
> This will allow us to:
> 1. Break things down into easily digestible chunks of information rather than having it in only long page.
> 2. Be able to update and publish information for previous and future releases immediately.
> Some of the wiki pages are buried deep down and may not be reachable from the wiki home page.
> It's also a bit confusing to find information from the two versions of the wiki home page
> https://cwiki.apache.org/FLUME/home.html
> https://cwiki.apache.org/confluence/display/FLUME/Home
> I like how projects like Apache Solr (http://wiki.apache.org/solr) and PHP.net (http://www.php.net/manual/en) organize information.
> I think we can learn a few things from how their project's documentation is structured.
> We could add comments to specific features, if they behave or should be configured differently in different versions/releases.
> What I would like to start with is:
> 1. Re-organization of the wiki home page to have a navigable table of contents carefully broken down into easy-to-digest sections.
> 2. Sections that document the overall architecture of the product. 
> 3. Sections that document the various features of the product (Sources, Channels, Sinks, Interceptors, DeSerializers etc).
> 4. Sections that document tips, techniques and processes for contributors, developers troubleshooting issues, active committers and PMC members.
> 5. FAQ index compiling and providing solutions to commonly-asked questions from the user and developer mailing lists.
> 6. Re-introduction of Flume explaining what it is and what it isn't. Also explaining use cases where Flume is applicable.
> Making this information readily available for new comers will really improve the rate of adoption and strengthen the community in the immediate future.
> Please add your responses and comments to this JIRA issue so that we can track it.
> Thanks.

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira