Red Hat Bugzilla – Bug 1276282
Can we please maintain a dedicated GitHub repository with all code examples quoted in our BRMS/BPMS documentation?
Last modified: 2015-12-21 06:28:46 EST
Section Number and Name:
Describe the issue:
- It has been observed quite often that customers come back to us through support cases with the following challenges (although these are not the exact quotations from customer cases but it can used for a reference feedback) while trying out the source code examples quoted in our official product documentation. Be it for BRMS or BPMS product, it can be related to Migration Guide or Development Guide or any other documentation related to these products.
1. The code examples which you have attached does not work for the latest version of the product. e.g. certain API changes made between BPMS 6.0.x and BPMS 6.1.0 were not reflected in the code examples shared in the documentation.
2. Your code examples which has been quoted in the documentation are not complete and hence sometimes customers need to spend some time to test it at their environment. In many occasion the code examples miss the imported fully qualified class names , preventing customers to fully understand the APIs used in the sample code.
3. The code examples quoted in the documentation has many errors and hence it appears that they were not tested properly.
Suggestions for improvement:
- What I would suggest as a positive starting point is to maintain a dedicated, supported GitHub repository (or any other source code management system you prefer) which you should use to maintain fully functional code examples which you quote in your documentations. And after each code example quoted in the documentation you can refer to the GitHub code repository link for customer's quick reference. After all we understand that it might not be always possible to copy-paste the entire code sample.
- Apart from that, I hope that after each new major/minor product release you guys test and verify those code examples from Engineering team or product SMEs. If those code examples pass the tests you should maintain versions of those code in the same GitHub repository as well which would adhere to the updated versions of libraries used in those code examples (corresponding to the new product release). So this would ensure that each code example is verified with the latest product library version. e.g. if BPMS 6.1.0 is released, the code example would contain the jBPM library version of "6.2.0.Final-redhat-4" which distinctively identifies that the code uses the appropriate product code.