Contribute to documentation

[tomfulton53]

I'd like to offer my services to make some badly-needed edits to the RichFaces user guide. How can I do this?

I am an IT trainer with a focus on JSF, course developer and technical writer, with a degree in English. Most of the edits I would like to make are simply to correct grammar for clarity.

Thanks.

[jbalunas]

This would be absolutly great!!

I would recommend creating a task in RichFaces jira using the "doc" component. Try to break down the issues that you would like to tackle into consumable parts - i.e. not "fix docs", but more like "fix grammar in the XXX section".

Then create a patch with the changes and attache to the jira. The docs team and I will keep an eye out for it. If they are not acted on post to this list and we'll take a look.

We are looking into ways to make this type of contribution easier to make, and we'll be posting more on this when it is decided.

Thanks,
Jay

[ilya_shaikovsky]

you could also contribute just to wiki cookbook section. then It will be available to the community even faster and then will be moved to documentation.

[tomfulton53]

I will check out the resources mentioned. I am focusing mainly on the richfaces-usersguide.pdf, and the grammar needs to be cleaned up throughout. However, initially, I would focus on Chapter 6: The RichFaces Components. Some sections are frankly pretty hard to understand as is, such as:

Section 6.3.4
The <a4j:param> extends <f:param> , so the "name" attribute is mandatory. Otherwise, the "value"
misses due missing the request parameter name for it.

I think that means:
The "name" attribute is mandatory. <a4j:param> extends <f:param>, so the "value" would not be found because the request parameter "name" would not exist.

As long as I'm planning on doing this, I will clean up more trivial examples of incorrect grammar throughout. There will be times when I need to confirm my understanding of a particular section...is this the correct forum for that?

[jbalunas]

Yup, this is the correct forum for that if you can not find it in the forum history. Just make sure to mention you are working on the docs :-)

Also I'm assuming you are familiar with the docbook system that generates the html and PDF files? In order to actually make these changes you will need to modify the docbook XML files and rebuild. It is really not that bad and a pretty good skill to have as a writer.

-Jay

[rruss]

This should be the best place to discuss those changes.

[tomfulton53]

I am not familiar with the docbook utility you mentioned. Can you point me at a resource for me to learn it?

I am assuming there is some original source document (or documents) from which the HTML and PDF are generated using XML. Can I get access to that as well?

Thank.

[ilya_shaikovsky]

If you have richfaces sources checked from repository you could find the docs directory here. userguide in this directory is a project which contains userguide sources.

Follow the link in my signature to get the link to sources if you haven't it locally. Also info about repository structure placed in our wiki.

[smukhina]

Hi, Tom
I also think that the best way to contribute to docs is to create a task and attach corrected xml files to it, the source xml files for docs can be found where ilya_shaikovsky has mentioned. Each component is described in 2 files <component_name>.xml and <component_name>.desc.xml, so when you correct these files you should validate them (most xml editors can do this) and attach the files to the task, also you can build the docs to see the resulted html or pdf, here is an instruction for building jboss tools docs http://www.jboss.org/community/wiki/BuildingJBossToolsDocumentaion, but its also relevant to rf docs.