Best Practices: Cross-Platform Documentation

[jgolds2]

As you point out in your article, no matter what platform you're on or heading to, good documentation is a universal need. What do you think about using Wiki technology for a documentation tool? We're exploring it's use and possibly housing it on the ISeries. The idea would be to build a composite of user, development and operational documentation with cross reference capabilities and if we make it useful enough and available enough it will be self correcting (well, that's if you believe Wikipedia is self correcting by it's wide acceptance).

[Guest.Visitor]

While Wiki technology is interesting, I believe it has limited formatting capabilities, and it is hard, if not impossible, to include documentation created in things like Visio.

[J.Pluta]

It's interesting that documentation has become something of a lost art. Java is the lone exception. Sun realized its necessity by embedding Javadocs right into the Java specification; that's gone a long way towards making Java easier to use. But no other language has any sort of built-in documentation. I'd like to come up with a very simple tool that would allow creation of basic documentation similar to Javadocs, with a syntax that could be used at least for RPG, CL, COBOL and even DDS. It wouldn't have to be pretty to start, but it would need to be configurable, both input and output. As to Wikis, my take on Wikis right now is that it definitely needs wide uptake by the group (whatever group that may be). As a tool for a single user (and I've tried it several times) either you spend to much time arranging it or else it becomes a little disjointed. Of course, a lot of that may be due to my own personal nature . Joe

[Guest.Visitor]

Joe, FYI. I was in an Anaheim COMMON class where the instructor mentioned something like "RPGDOC" that he developed and the handout included a sample of code. It may have been Paul Touhy but I just don't recall for sure. Chris

[J.Pluta]

I heard about something, Chris, but I can't seem to find it. Aaron Bartell coined the term back in the mailing lists eons ago, but I thought someone else had picked up the ball and run with it. However, I can't find it anywhere, so maybe the project sputtered out. Joe

[Guest.Visitor]

Joe, I have to disagree with you that documentation should be kept in a binder or in paper form. I've been in too many shops that waste space for binders that never get updated. I was recently hired on as an employee by one of my clients. My first day, I was confronted with binders and books of printouts and reports that documented everything on the AS400. The problem is that it is dated 1998. What good does that do me now? It's so outdated that many of the libraries, job descriptions, and user profiles no longer exist. Other binders have screen layouts, DDS printouts, and program flowcharts drawn by hand. Most of this documentation is from 1988 to 1991. That was common practice then. We have many more options today. It's easy to write a chart in Visio and link to it from a Word document and store it on a network share. The difficulty comes in organizing the folders and having consistent naming conventions for the documents. Programs and systems change through the years. It is much easier to store this information in search-able electronic form. It's also much handier when you want to look something up. Tom.

[J.Pluta]

Yes, this looks like the project. I'll do some more research to see where they are with this. Joe

[J.Pluta]

Tom, I had to go back through the article carefully to make sure, but sa far as I can see, I never said anything about a binder. While we certainly did use paper documents back in the 80s, I think nowadays you'd want something more dynamic, delivered via a browser or a thick client. My biggest concern right now is whether the information should be stored in a database and then served up via XML, or stored originally as XML. I have problems with the latter, but that may just be the dinosaur in me rearing its head . Joe

[Guest.Visitor]

Hey Joe, (I just listened to Jimi Hendrix). This is a quote from the article. " And Now We Return to Our Regularly Scheduled Article This brings us back to the issue of documentation. Even if you do have consistent naming for each of your fields, those definitions should be further codified in a binder that identifies these field names and their functions. Let's take a look at a field definition:" I like your idea of using XML and browser access. I'll have to think about that at my new place. Tom

[J.Pluta]

That was an unfortunate word choice. I definitely should have used the word "repository" rather than "binder", because I really wasn't thinking of paper documentation. Maybe that was just an acid flashback, man. I do recall having shelves full of metal binders in which you could find paper documentation. Yikes. Anyway, sorry about that. I looked throughout the article and didn't see it anywhere else. Please tell me that's the only place I used the word! I'm continuing on with my cogitation, though, as to whether the ILE documentation should start life in DB2 files and then be exported to XML when needed, or whether the base documentation store should simply be XML and the ILE is generated into that like any other platform's information. The upside to the intermediate DB2 format is that it's available to pretty much anyone who knows a System i, and with the ubiquitous nature of SQL, it would be easy to query that stuff. And if you didn't really have much in the way of cross-platform, you might not ever need the XML. The downside is that you need to keep two repositories up to date, the DB2 side and the XML side. Decisions, decisions. Joe