Documenting Notes Development
We all know: developers are to documentation are like cats to dogs. There are cute pictures of co-existence in the internet but in reality one chases the other in a never ending fight. One of the big reasons: nobody reads documentation until a problem occurs or there is a change of watch, none of which appears in either "important" or "interesting" category of a regular developer. A partial solution for this dilemma is to automate documentation creation. I'm fully aware that a lot of generated documentation is not very useful, so be careful what you wish for.
What I describe in the following is not something readily available, but it would make an excellent plug-in for the Domino Designer (if I can find some brothers in crime). Some of the tools are ready, some need to be created and all of them need to be glued together in an automated process. So this is how it can look like:
What I describe in the following is not something readily available, but it would make an excellent plug-in for the Domino Designer (if I can find some brothers in crime). Some of the tools are ready, some need to be created and all of them need to be glued together in an automated process. So this is how it can look like:
- The documentation process would be governed by an Apache ANT script. Such a script can be run from within Domino designer and you even could automatically run it whenever you run a build of your application
- Ideally the reports would run (makes things easier) on individual files and, for cross design element reports, on a summary file. When connecting an NSF to a version control system, the individual files are created on the file system, so that's sufficient (or you can use Guo Yi's Import/Export plug-in (which incidentially has an ANT interface ) or call DXLMagic from the ANT script (it is like calling a command line Java) with the DesignExtractorSINGLE mode. DXLMagic useful for classic stuff, not for XPages, so you stick to the export tool or the version control for these
- Run XSLT based reports on the XML: View selection formula, XPages field validation, Buddy list reports, Hide-When formulas, Replication formulas, Field reports, View structure, XRef documents etc.
- Use JavaDoc to document all Java classes you might have used
- Use LSDoc to document your LotusScript (how to get all of it into a script library is subject to a future post)
- Use JSDoc to document all the JavaScript
- Use Visustin to generate flowcharts from all the language source code. With a little tweaking the *Doc generators can be tweaked to include the images of visustin (after all it is just HTML which could be post-processed)
- Use Crap4J to check for the quality of the Java used (CRAP stands for: "Change Risk Analysis and Predictions")
- Use JSHint to check all the JavaScript (based on some opinion it will work better for our purpose than the original JSLint
- The missing piece: LSLint. It would be way cool to have something like that. On the other hand: some code better should not be scrutinized
- Finally all results are uploaded into one WIKI (or another), so the WIKI would take care of "what has changed"
Posted by Stephan H Wissel on 29 November 2011 | Comments (3) | categories: Show-N-Tell Thursday