Documenting Interface Code – How to

Clovertech Forums Read Only Archives Cloverleaf Cloverleaf Documenting Interface Code – How to

  • Creator
    Topic
  • #55505
    Tipu Razaq
    Participant

      Hi Everyone,

      How do you guys go about documenting code written either in an xlate, or tcl at your work?

      We have a requirement to have our interfaces documented well enough that in case of a disaster we can recreate an interface, code and all, by reading a document.

      Currently we have an Excel sheet that’s recording what segments we send, variants, tables/maps that are used, but not the actual code itself. I don’t know of a way to really do this besides taking screenshots of the actual code from the Cloverleaf GUI, but I’ve been told we need an alternate way instead of screenshots.

      So how would you guys go about it?

      Any info. is appreciated,

      Thanks

    Viewing 5 reply threads
    • Author
      Replies
      • #85575
        Sophie Chege
        Participant

          We document our tcl’s  really well to ensure that if one of us gets hit by a bus, the rest of us can follow their code but for interfaces, we have a job that tars up the sites in entirety and they are backed up in our disaster recovery locations, as well as having an active:passive structure in case the active box goes down.

        • #85576
          Tipu Razaq
          Participant

            Sophie Chege wrote:

            We document our tcl’s

          • #85577
            Dustin Sayes
            Participant

              The .xlt is pretty easy to read and follow in most cases. Write a program to read through the .xlt then output as step by step statements.

            • #85578
              Tipu Razaq
              Participant

                Dustin Sayes wrote:

                The .xlt is pretty easy to read and follow in most cases. Write a program to read through the .xlt then output as step by step statements.

                This is interesting. Do you know of a way? Are they any hci commands that can parse an xlate?

              • #85579
                Jim Kosloskey
                Participant

                  Have you looked at the provided SiteDoc tool?

                  Although I don’t know if you can print the docs out. Couldn’t in the releases I used (last 6.0) but maybe in later releases the capability was added.

                  The .xlt files are made up of Tcl Lists and keyed lists.

                  I do not know of a module to parse that but there very well could be. I am not sure that if there is one it is supported to be used as an API though.

                  Here is my .02 on the subject (may not even be worth that):

                  I would find it really surprising if after the docs were created, allocation for resources would be made to keep them maintained. That has not been my experience anyway.

                  Even with documenting all you can, there are nuances to almost every integration which do not translate well when trying to create from the documentation. The doc is great if there is a system to observe and exercise to see the nuances.

                  The most workable in my opinion is to have a really good set of specifications. In this day of instant integrations who does that anymore? Also whatever documentation which indicates what is needed to be done in addition to the specifications (here is where the nuances could be identified). Then in the case of an emergency where no restoration is possible, capable Integration Engineers would take the specification and said docs and rebuild the Integration from scratch. They might build new Tcl or new Xlates to do the same thing rather than brainlessly rebuild. Who knows new features of Cloverleaf may be better than the way it was done.

                  But re-read my first point.

                  OK – now I will put on my conspiracy hat. Whenever in my 52+ year career in computing I hear this request (and I have heard it a few times) it was almost always followed with an attempt to replace the staff in one way or another. I hope that is not the case there.

                  email: jim.kosloskey@jim-kosloskey.com 29+ years Cloverleaf, 59 years IT - old fart.

                • #85580
                  Jim Kosloskey
                  Participant

                    Oh one more point – I am of the opinion (which is reinforced almost daily) that not ‘just anyone’ can build meaningful integrations.

                    I have had to assist in way too many integrations built by ‘just anyone’.

                    Others may and probably do disagree.

                    email: jim.kosloskey@jim-kosloskey.com 29+ years Cloverleaf, 59 years IT - old fart.

                Viewing 5 reply threads
                • The forum ‘Cloverleaf’ is closed to new topics and replies.