In moving from RichFaces 3 to RichFaces 4, the documentation of the porjected fragmented, as we aimed to improve the accessibility of the docs, as well as turning towards more automated documentation generation.  In RichFaces 5 we'd like to look at whether/how these docs can be re-assimilated to provide all members of the RichFaces community with an optimal documentation experience.

To facilitate this goal, this wiki page will capture a set of user stories of how we would like to see the documentation used with RichFaces 5

User Stories

1. As a RichFaces user I want to
   • have a single reference for all aspects of using a component
     • so that I don't waste time parsing different documentation sources
   • have the documentation available in both PDF and HTML format
     • so that I can have the docs easily accessible when offline
   • find best practices and recommendations in documentation
     • so that I can learn useful information about using components
   • have a link to VDL documentation in docs
     • so that I can find outstanding up-to-date information about tags directly
   • have a link to Showcase
     • so that I can review discussed topics in a sample
2. As a RichFaces developer I want to
   • maximize the amount of documentation that is generated from source
     • so that I can reduce the maintenance cost associated with keeping the documentation up-to-date
   • have the documentation available in docbook xml format
     • so that I can meet the requirements of the downstream WFK product
   • easily preview what the rendered documentation will look like
     • to reduce the documentation authoring turnaround time
   • easily navigate to the documentation source
     • so that I can quickly modify docs as I find issues