2 Replies Latest reply on Aug 15, 2011 7:46 AM by Mauricio Salatino

    Community Contribution to User Guide?

    Tobias Wittur Newbie

      Hi,

       

      I ve been fiddling around with jBPM for about 2 weeks and I realized that I quickly reached a point where the user guide could not help me anymore. To be honest, it was sometimes a bit frustrating.

       

      In my opinion, there are quite a few stumbling blocks with jBPM especially for novice users. The documentation however, does not make it much easier. Most of the information is dispersed in different blogs, wikis and forum posts. I really appreciate the support that I received in this forum, however, it slows you down of course - if you have to wait for a reply.

       

      Especially the tooling side could be better documented. My personal perception is, following the issue tracker a bit, that there is a lot of work about to be done for the tooling side. Since there are changes/new features about to come, it would be good if there was more involvement from the community in the user guide. So the user guide can be up to date.

       

      Therefore my question, how exaclty can we contribute to the user guide and enrich it, so that other beginners have it a little bit easier? Is that possible already and I just did not see where?

       

      Best regards,

       

      Tobias

        • 1. Re: Community Contribution to User Guide?
          Esteban Aliverti Master

          I agree wit you. It would be great if the community could help in the documentation area. The documentation is a good starting point for further contributions like patches and new features. If you want to start helping with the documentation you need to have a basic knowledge in these technologies/applications/frameworks: 

          • git: JBPM project is hosted in Github (https://github.com/droolsjbpm/jbpm). If you want to start digging in the source code or in the documentation the best thing to do is to create a Github account and to fork jbpm project. Once you forked it you need to clone it to your computer. The documentation is under jbpm-docs directory. I would reccomend you to create different branches for the different features you are working on.
          • dockbook: JBPM documentation uses dockbook. This framework allows you to create documents using xml. You can start at looking how the current documntation is defined to get confortable with it.
          • maven: this is the build system used by JBPM. Once you have made all your changes and additions, you can create the resulting PDF document or HTML using maven. A simple "$mvn clean install" will do it for you.

          When all the changes and additions are ready, you can create a Pull-Request from your fork (and branch) to jbpm repository using Github UI. A Pull-Request is the way Github uses to merge changes from different (but related) repositories. Someone from the JBPM team will review your changes, and apply them (if they are ok).

           

          For further instructions on how and where you can start contributing to the documentation, please visit #jbpm channel in irc.codehaus.org

           

          Good luck! I hope to start seeing your Pull-Requests soon!

           

          Best Regards,

          • 2. Re: Community Contribution to User Guide?
            Mauricio Salatino Master

            That's right. If you want to add some documentations bits about the tooling we can help you with the GIT stuff, but you need to at least write the docs using the docbook format that is plain XML. You can take a look at the docs files in the repo that Esteban mention. More specifically here:

            https://github.com/droolsjbpm/jbpm/tree/master/jbpm-docs/src/main/docbook/en-US

             

            We don't want to slow down your contributions so we can help you with the administrative part if you provide content

            Cheers