Open Source on IBM i

ILEDocs Revival

Hi,

creating documentation has always been a major PITA in software development. Tools try to ease the process of creating good documentation. There are different kind of documentations (mostly different by the scope and/or detail and/or perspective) and not every documentation tool is good for every kind of documentation.

API documentation is one kind of documentation. It is rather easy to create in most programming languages as there are many good toolchains like Javadoc or doxygen. Sadly for development on IBM i you will not find a good toolchain or documentation support on our beloved platform for your own development (I am not talking about the IBM i Information Center).

I tried to tackle this problem once with a not so pretty solution. Especially installation and maintenance was not very well thought out. Editor support was also not very good or even non-existent.

Now some years later and with new technologies appearing I have a feeling that I can tackle this problem much better and easier than before. I revived the ILEDocs project with a fresh approach using Dropwizard for the backend and AngularJS for the frontend. A MongoDB database will store the documentation.

Updating the documenation is now tooling independant as we can work with a REST service and just need to upload a JSON document.

The MiWorkplace editor will get some extra features like querying the documentation database and updating the documentation directly from the editor.

The documentation could also be updated from some workflow like a TurnOver form run utilizing the old ILEDocs RPG and CL parser, converting the parse result to JSON and sending it with the HTTP Client to the ILEDocs REST service. Though this is not implemented.

The project is not finished but already quite usable. It is open source and available under the Apache License 2.0.

You can take a look at it at bitbucket.org. The wiki at the bitbucket project site contains some useful information on how to setup your own documentation server.

One of my goal is also to create a universal documentation server for all open source IBM i projects. Please contact me if you would like to help.

A prototype is also already online with some demo content at iledocs.rpgnextgen.com. Feel free to give it a try.

I would like to hear your thoughts and feedback.

Happy documenting!

Mihael

Tags : ILEDocs