The Importance of Mainframe Documentation

The discovery of Egyptian hieroglyphics was the event that led to the definitions of the formal writing system that was once used in ancient Egypt as part of the native language. Egyptian hieroglyphics had more than 1,000 distinct characters that were used to tell the stories associated with the time. In the same vein, telling the “stories of the time” is important in any mainframe environment. Proper documentation is the key to a well-built and solid mainframe environment that leads to operating efficiencies of scale.

One of the reasons proper and complete documentation of mainframe environments is so important is the demographic of the typical mainframe employee. According to Zippia, the average age of a mainframe operator is 42.7 years (and 45.3 for mainframe developers and 40+ for mainframe systems administrators). My point is that people in their 40s can leave a company at any time for other opportunities. They’ve built their careers via experience, knowledge and networks that make them all valued commodities. Additionally, people that started their careers in the 1970s and 1980s, smack in the middle of the mainframe age, are now at the ends of their careers. Some estimates placed more than 85,000 open job requisitions in the field as of 2020, and that number has only grown today. Underscoring this topic is the fact that the mainframe is not going away anytime soon. 

With the constant danger of job changes and retirements, maintaining mainframe documentation across your organization is more important than ever.

I recently worked with a major corporation that was offering an attractive retirement package to reduce its workforce. The company was surprised when 20% more employees than projected had decided to take the offer. Immediate red flags went up with the thoughts that its mainframe environment was poorly documented and the people taking the retirement package would be walking out the door with the mainframe knowledge that they had built over the lifetime of work with the corporation. What the company needed was a plan to make sure that did not happen.

Part of our Kyndryl US mainframe strategy includes an INSight Assessment of Documentation. Our approach to mainframe documentation assessment consists of three steps: 

Step 1: Review Mainframe Documentation

This step includes a detailed review of the existing mainframe documentation, including:

Current mainframe diagrams and architecture

• Mainframe configurations for all machines
• Mainframe hardware list (CECs, all storage, routers, switches, etc.)
• Topology diagrams of all mainframes and hardware (devices, internal and external connections, IPs, LPAR, SYSPLEX and LPAR purpose/breakdown)
• DASD and VTS storage diagrams that show hardware, type/model, description, S/N, DASD volume models, useable vs. installed capacity, LCUs, pools, how accessed/sharing, etc.
• Security diagram/explanation (DBs, access controls)
• Network diagram of interfaces to mainframe

Current mainframe reports

• RMF report
• Logger data
• Latest capacity and performance report(s)
• I/O, memory, storage capacity/performance report(s)
• SCRT report
• TADz reports for all CECs, LPARs, plexes, etc. 

Step 2: Conduct Informational Interviews   

This step is comprised of in-depth interview sessions with customer teams, including IT employees that work on the mainframe, business line managers and the leadership team. The executive team decides which teams are needed, and we collect information through one-hour interviews.
 
Interviewees may include:

1. Subject matter experts (SMEs) that support the mainframe layers below the applications, such as:
   • SYSPROG/MVS
   • Capacity/performance
   • IMS CICS
   • Db2
   • MQ
   • Storage
   • Hardware
2. Mainframe operations managers
3. Data center planners
4. IT program managers
5. Key line-of-business leaders
6. Key development leaders 

Step 3: Make Recommendations

In the third step, we deliver a detailed findings and recommendations report to the customer. The following categories are presented:

• Observations and gaps
• High-level observations from each team interview
• Observations are prioritized (as a method of showing value of each one)
• Recommendation’s summary
• Detailed recommendation list
• A 1-10 rating of the organization’s current mainframe documentation
• Final recommendations
• Short-term strategy recommendations
• Long-term strategy recommendations

After each team interview is conducted, we produce a report of each interview that covers which team members were involved and captures highlights and high-priority gaps. Each team is scored for “documentation level” from 1-10. Then, we meet with the sponsoring executive to provide feedback on quick action items and major gaps. This information is in the final report, but this gives the executive a chance to immediately hear the feedback from each team. It’s not uncommon to interview 25–30 teams, depending on the size of the organization and geographies. 
 
High-level observations from each interview are also noted in the report. Each observation is assigned an impact score and term (i.e., impact=high, medium, low and term=long or short). This a good way to immediately assess the impact of the observations and the timing as for when to address them.
 
The high-level observations taken from each team are then prioritized and ranked based on expertise from Kyndryl SMEs and an impact score measuring overall impact for all observations in the customer’s environment is noted.

Final Recommendations Report

One of the most important deliverables of the mainframe documentation study is the Final Recommendations from the Documentations Interviews Report. This report is key as it can immediately be used to brief the executive team on findings, recommendations, and next steps. The format used shows the recommendation, best practices to fill the gap and how many times certain topics surfaced during all the interviews. The top 8-10 recommendations are highlighted. Finally, we calculate an overall documentation level on a 1-10 scale.

All the teams’ documentation levels are totaled and divided by the number of interviews. For instance, a total score of 165 divided by 21 teams interviewed would yield a documentation level score of 7.85. Additionally, a total is used to show how many times the topic surfaced during our interviews. The key for the customer is an indication of the overall strength of the mainframe environment from a documentation point of view. Repeating topics are identified and can be addressed.
 
While the Mainframe Documentation INSight Assessment is a great tool to ensure that an organization’s mainframe documentation is adequate, accurate and acceptable—the strategy behind these assessments highlights the importance of having effective mainframe documentation in place. A well-planned mainframe documentation strategy also protects the organization as employees leave the company or take other jobs. In the same spirit as Egyptian hieroglyphics, you need to know your mainframe documentation is solid, and make sure it can tell the “stories of the time.”
 

---