wissel.net

Usability - Productivity - Business - The web - Singapore & Twins

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:
  1. 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
  2. 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
  3. 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.
  4. Use JavaDoc to document all Java classes you might have used
  5. Use LSDoc to document your LotusScript (how to get all of it into a script library is subject to a future post)
  6. Use JSDoc to document all the JavaScript
  7. 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)
  8. Use Crap4J to check for the quality of the Java used (CRAP stands for: "Change Risk Analysis and Predictions")
  9. Use JSHint to check all the JavaScript (based on some opinion it will work better for our purpose than the original JSLint
  10. 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
  11. Finally all results are uploaded into one WIKI (or another), so the WIKI would take care of "what has changed"
What would you add? What XML/XSLT driven reports could be created?

Posted by on 29 November 2011 | Comments (3) | categories: Show-N-Tell Thursday

Comments

  1. posted by Christian Zalto on Tuesday 29 November 2011 AD:
    The missing piece would be a bot to read through all this generated documentation.
    As you mentioned "a lot of generated documentation is not very useful" - so why would you still want to create it? You can add more tools and still not have anything useful, that's not already in the code.
    Better document the business processes the application is relevant for, document the requirements, document your test plans and test result, write an end user documentation and a description of interfaces and critical points for troubleshooting.
  2. posted by Stephan H. Wissel on Wednesday 30 November 2011 AD:
    Christian, you are right, the parts I listed are code centric. I appreciate your readership and comment. While I said "a lot of .... not very useful" it doesn't mean "all of it". What I tried is to highlight how to make generated documentation more useful. Having a code flowchart and all comments is IMHO very useful. And having a (wiki) button that shows what has changed too.
    I disagree on "document the requirements" - that's not a developer's Job. Ideally that is done by the Analyst in a continuous matter while the software is evolving, having a wiki like versioning is gold here (and yes: In Notes we are often Business-Analyst-ProjectManager-Developer-Documenter-Tester-FirstLineSupporter instead of core developer).
    The critical point for trouble shooting can come from the LSDOc/JSDoc/JavaDoc. As a developer while I code it is way more efficient to just add a comment that going anywhere else - and the *Doc would pick it up.
    Interfaces and sequences are a bid of a headache. There was a plug-in to Rational Architect that converted NSF into UML, but I don't know if it ever was released.
    And test plans? Emoticon biggrin.gif Isn't (tongue-in-cheek) the common test practice: Throw it at the user in a critical moment and hide until the screaming subsides.
  3. posted by Patrick Kwinten on Wednesday 08 February 2012 AD:
    placing the documents into the XPages Documentation Wiki I would consider the weakest link. Just look at the defects reported and how IBM has responded with updated releases. (same applies for the xpages wiki { Link }