Software Engineering

Documentation for lazybones with SoaDoc

process

Documentation is an aspect of software development that is not the favorite of everyone. Especially the documentation of SCA is difficult because of many components and references. For this reason I am using the SoaDoc solution by esentri. SoaDoc generates a fast and meaningful documentation of composites and BPEL processes.

SoaDoc takes the information from the composite.xml and the BPEL files. To get the best of this documentation it is possible to describe the steps of the process in JDeveloper. With a double-click on the component you can see the documentation tab, that will be translated into the XML structure.

Documentation_radiology

The generated documentation will be a browsable website with two navigation section, one for the composite and one for the BPEL processes. If it’s needed it’s possible to generate the documentation upon more than one composite, to get an application-wide documentation. The source path of the SoaDoc application will control this.

process

As an example I took the Health Care process FPScenario7 to add the documentation like described above. After that we figured out the best integration is an Ant or Maven Task that start a „site“ goal. The configuration for the source and destination path will be handled by the build.xml or the pom.xml. The third parameter is the language, we support English and German.

ant_site

In the destination path the index.html is the start point and the content folder have all other information, like HTML sites for the processes and images for the representation.

bpel_site

In the BPEL descriptions the process steps are presented in a table with the level of depth and an image for the element. All information like attributes, child elements or the documentation entry, from the JDeveloper, are shown in the description column.

sca_site

In the composite.xml it’s harder to document, therefore we can create a composite.html in the same directory to describe the composite.xml. The documentation will be appear between the composite title and the service endpoints. The other information will be shown on this site the service endpoints, the components with links to the detail site and the references that were called.

For everyone who has to produce documentations: SoaDoc is a simple solution to document composites. If there are wishes for the representation of the sites or some other features there is only a little customizing needed. If you are interested in the solution feel free to contact us!