8 Replies Latest reply on Apr 10, 2009 2:44 PM by Svetlana Mukhina

    Contribute to documentation

    Tom Fulton Newbie

      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.


        • 1. Re: Contribute to documentation
          Jay Balunas Master

          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.


          • 2. Re: Contribute to documentation
            Ilya Shaikovsky Master

            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.

            • 3. Re: Contribute to documentation
              Tom Fulton Newbie

              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?

              • 4. Re: Contribute to documentation
                Jay Balunas Master

                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.


                • 5. Re: Contribute to documentation
                  Rodney Russ Newbie

                  This should be the best place to discuss those changes.

                  • 6. Re: Contribute to documentation
                    Tom Fulton Newbie

                    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?


                    • 7. Re: Contribute to documentation
                      Ilya Shaikovsky Master

                      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.

                      • 8. Re: Contribute to documentation
                        Svetlana Mukhina Newbie

                        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.