[
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
