On Feb 21, 2005, at 11:49 AM, Sean Schofield wrote:
I have a few suggestions on how we might be able to improve our documentation and examples.
1.) Stop putting examples into the tabbed panel and menu. While this is nice to have in order to show off the tabbed panel, menu, etc. it adds a lot of code to the example page that is not relevant to the component in question. There are issues with subview, verbatim, etc. that just confuse the issue. I suggest that we rework the individual component examples so that they can stand on their own.
I agree. Simple is much better as we move out of the incubator and more people that are unfamiliar with JSF start to join the flock good docs will save us tons of work.
2.) Make the examples available in the documentation of the components. It would be nice if you were interested in the date control to click a link and read about it and then see an example of the component on the same page.
Not sure I follow. Do you mean adding the JSP goop that you should use in the java doc? If so I agree.
3.) Include the JSF source of the examples on the example page. It would be nice to see the actual JSF that produces the component when reading the documentation and looking at the example. Of course, the source code can be downloaded and examined, but for the casual user investigating myfaces, it would be nice to just see the JSF right there. We could probably do some interesting tricks with ANT scripts and <f:verbatim escape="true"> to auto-generate this source.
Same question as above.
4.) Develop a standard template for component documentation and examples. This really just means standardizing on items 1-3 (or some other set of standards.) Each component's web documentation should have the same look and feel to it with roughly the same layout.
Agreed, then we can auto generate all the docs...
I am bringing these issues up now because I think it might be something we want to address as MyFaces leaves the incubator. I will be happy to help with whatever the group can agree on.
sean
Thanks Sean!
-bd-
