Unconfigured Ad Widget

Collapse

Announcement

Collapse
No announcement yet.

Best Practices: Cross-Platform Documentation

Collapse
X
 
  • Filter
  • Time
  • Show
Clear All
new posts

  • Best Practices: Cross-Platform Documentation

    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).

  • #2
    Best Practices: Cross-Platform Documentation

    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.

    Comment


    • #3
      Best Practices: Cross-Platform Documentation

      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

      Comment


      • #4
        Best Practices: Cross-Platform Documentation

        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

        Comment


        • #5
          Best Practices: Cross-Platform Documentation

          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

          Comment


          • #6
            Best Practices: Cross-Platform Documentation

            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.

            Comment


            • #7
              Best Practices: Cross-Platform Documentation

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

              Comment


              • #8
                Best Practices: Cross-Platform Documentation

                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

                Comment


                • #9
                  Best Practices: Cross-Platform Documentation

                  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

                  Comment


                  • #10
                    Best Practices: Cross-Platform Documentation

                    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

                    Comment


                    • #11
                      Best Practices: Cross-Platform Documentation

                      Talk about dinosaur. What's the first thing that pops into my head when I read binder? Three rings and lots of paper Ha! Too funny. I should have known better what you meant. Sorry about that. Tom

                      Comment


                      • #12
                        Best Practices: Cross-Platform Documentation

                        In fact, with Mediawiki Wiki software you can store any kind of document or data in the wiki and keep multiple versions. I did a session at Anaheim on installing & using a wiki for maintaining documentation for multiple platforms, including As400. The people from Zend had a demonstration project up of running Mediawiki on as400 - I'm not sure if it was running on mysql, or if the code had been modified to use db2/400..

                        Comment


                        • #13
                          Best Practices: Cross-Platform Documentation

                          The reason is that code in Java is much more split up in little pieces (it should anyway), it's more granular. So when documenting each method and class the javadoc can produce nice docs which have also a clear context (a class, a method, etc). But in RPG, programs are much more monolithic. So this only works when the program is devided in little procedures/subroutines (preferably only procedures of course) which are nicely focused (do just one thing) and have clear names. The source needs to be "self-documenting" before an RPG doc utility would have any use (after all it's just a simple tool). Comments for procedures/subroutines etc can be filtered out of course and placed in a document but there is much less context as in a java program. gr. jacobus

                          Comment


                          • #14
                            Best Practices: Cross-Platform Documentation

                            ** This thread discusses the Content article: Best Practices: Cross-Platform Documentation **
                            0---0

                            Comment

                            Working...
                            X