technical: The Right Documentation

A few months ago I wrote a document recommending a change to a client to reduce their CPU usage. One of the primary documents I used when researching this recommendation was an IBM Redbook dating back to 1995: 22 years old. This sounds crazy, and in most cases it would be: z/OS and related software is always changing. However in this case, the reference was still valid. But how?

Product Documentation

One of the easiest mistakes we can make as technical people is to use out-of-date documentation. Every new release of z/OS, CICS, Websphere MQ or any other software brings changes: changes to parameters and configuration, changes to messages, changes to how things work. Every product generally will have a new set of documentation for every new release. However it's not just out of date documentation. Using documentation 'in advance' of the current software release is just as dangerous. So if you're using CICS TS 5.2, you should be using 5.2 documentation, not 5.3.

This is an easy mistake to make when our first port of call is to use Google or similar search engines to look for areas of interest. We get a Google hit in an IBM manual, jump to that page and start reading.

The good news is that IBM have recently made a change to many of their information centres to help fix this. These pages now show the release of the product that it relates to. Even better, there's a drop-down box we can use to jump to a similar page or section for the product release we're interested in.

Supporting Material

Ideally, we could rely solely on production documentation for anything we do. But in practice this doesn't work. So as technical people we look for supporting material. One of the first to come to mind are the Redbooks produced by IBM. Other source could include Share or CMG proceedings and presentations, YouTube videos from vendors, 'wiki' sources, IBM developerWorks, or web articles from sites such as Longpela Expertise and Cheryl Watson. We talk more about supporting material in our partner article.

Using such supporting material can be more of an issue. In another partner article, we talk about who produces this supporting material, and ways to determine if it is qualified and unbiased.

But the timeliness of this supporting material is also important. For example, this z/Journal article talks about Enterprise Java Beans (EJB) on CICS. Now, this article was accurate when it was written in 2004, however CICS no longer supports EJB. This article has done well, and specified the CICS version in the title "A Closer Look at CICS EJB & Java Support Under CICS TS 2.3". So that's an indicator that it may be out of date.

IBMs Redbooks also can also have this issue. For example the Redbook "IBM Tivoli Storage Management Concepts" states that Tivoli Storage Manager Server can run on z/OS. This is no longer the case.

Choosing Wisely

Simply being aware that some technical content may be out of date is a big step forward in preventing mistakes from incorrect material. So we now know to use the correct version of manuals. Also reading supporting material is also helpful. For example, the z/Journal article discussed above specifies the (outdated) CICS version in the title. Similarly the Tivoli Storage Management Redbook actually states that that version 5.3.3 (an outdated release) servers are supported on z/OS.

Conference proceedings will all specify the year when the presentation was performed, articles will have a date published, and most supporting documentation will have a date somewhere attached. So it's simple: the older the material is, the less likely that it will be relevant.

This doesn't necessarily mean that all old resources are of no use. However enough knowledge or supporting research is required before using it. For example, in 2006 David Bond of Tachyon Software performed the presentation "Coding Assembler for Performance" at Share in Baltimore. Although 11 years old, most of the information included here is pretty good.

Conclusion

The Redbook I used was actually the IBM ITSO publication "System/390 MVS Parallel Sysplex Batch Performance" published in December 1995. Some of the data is outdated, but this still has the best explanation of QSAM and BSAM buffer usage and tuning that I've seen. Supporting research and experience has shown me that little has changed with QSAM and BSAM buffering and tuning over the past 22 years. So the reference is still valid.

The fact is that most of us (including me) use Google as the primary search tool for technical content. This is a great tool, however care should be taken to ensure that material that Google finds is accurate and up (or down) to date.

David Stephens

LongEx Quarterly is a quarterly eZine produced by Longpela Expertise. It provides Mainframe articles for management and technical experts. It is published every November, February, May and August.

The opinions in this article are solely those of the author, and do not necessarily represent the opinions of any other person or organisation. All trademarks, trade names, service marks and logos referenced in these articles belong to their respective companies.

Although Longpela Expertise may be paid by organisations reprinting our articles, all articles are independent. Longpela Expertise has not been paid money by any vendor or company to write any articles appearing in our e-zine.