Documenting Interface Code – How to

[Tipu Razaq]

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

Topic

[Sophie Chege]

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.

[Tipu Razaq]

Sophie Chege wrote:

We document our tcl’s

[Dustin Sayes]

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.

[Tipu Razaq]

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?

[Jim Kosloskey]

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.

[Jim Kosloskey]

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.

[Author]

Replies