Creating Content for Next-Generation Mainframers

For 80 years, the mainframe industry has served critical business domains: banking, finance, health care, insurance, utilities, and the government. The industry is amidst a massive loss of expertise due to retirements. These veteran mainframers have established specialized skills and acquired significant domain/product knowledge using mainframe software over their long careers. The replacements for the retiring mainframers are often new to the platform.

When designing solutions for new mainframe users, our goal is to deliver an intuitive and productive experience that does not require considerable content or ramp up time. And yet, the mainframe, its workload, its complexity, and its critical scope may require detailed procedures to install, configure, maintain, and use certain features.

When detailed content is required, we employ the following specific tactics to deliver content for next-generation mainframers.

The WHO

For all content, but especially technical content, establishing the audience is the key starting point. Doing so lets the reader know that they are in the right place. A security administrator is likely not concerned with deep-dive database administrator content. Taking it a step further, we identify personas (typical users/content consumers) so that we understand the information that those users likely need.

For example, we often create content for next-generation mainframers (system programmers, security administrators, storage administrators). This persona likely has a computer science or engineering degree, with novice-to-intermediate mainframe skills and experience. This persona likely needs more information than the veteran mainframe operators who are now retiring. For much of our content, we focus our efforts on helping the next-generation mainframer persona across multiple administrative roles.

The WHY

In all technical content (procedures, concepts, and so on), closely after identifying the audience, we explicitly state the goal of the content (configure a widget) and why doing so offers business value (to meet a government regulation). Audience and purpose are the foundations of useful content.

For example, “The security administrator can now manage the system controls in the user interface. We previously stored and managed these system controls in the product configuration file (XX11YY22, by default). Managing system controls from the UI simplifies the process because you do not need to issue console commands and edit configuration files to do so.”

The WHAT

Scenarios

We have the who and the why. Now we need the what…the larger, primary content vehicle. The complexity of the mainframe dictates that we create our fair share of procedures. To do so, we employ scenario-based content, which provides information and guidance based on specific usage scenarios or real-life situations. Rather than presenting information as a feature overview, scenario-based content addresses the needs and challenges that users face in their specific tasks. Scenarios help users understand how to use a product in a practical and memorable manner.

Scenario snippet, including the why, the who, and a workflow diagram

Templates

Many of our customers use multiple products from our portfolio to manage their mainframe ecosystem. As they consume content from these products, they expect and deserve a consistent experience. To support this business imperative, we employ documentation templates for release notes, installation, upgrade, messages, and more. Doing so ensures that users can find information in a similar location regardless of the product. Also, our writers are more efficient because they can reuse accessible and tested content.

Job Aids

Installing, upgrading, configuring, and maintaining mainframe software is a complex, multi-role process. We built fully reusable template topics for many of these use cases. We also employ job aids to help all roles understand the full scope and their responsibility in the process. To do so, we create intentionally simple checklists. Each checklist includes a brief description of the tasks, with links to the comprehensive information required for the process (for example, install or upgrade). The checklist also identifies the roles that are typically required to complete the task, which enables the installation team (systems programmer, security administrator, and so on) to focus on the tasks for which they are responsible. We make this job aid available in HTML but also in a downloadable xls file. With the latter, teams can house it in a local repository and use it as a project management tool to track progress.

Snippet of a typical software installation checklist

The DETAILS

Within an actual scenario, template, or any content really, we employ the following granular technical writing tactics to help the next-gen mainframer:

• Tell the user why they are completing a step or procedure. For example, “Submit the deployment jobs in sequential order, wait for each job to complete, and then select Refresh to register job completion in z/OSMF.”
• Ensure that major steps include an outcome. In doing so, the user knows when they can move to the next step or procedure.
• Include multiple real-world examples and best practices. While we cannot document every example, by sharing several examples in each scenario, we can help users see how they can extrapolate an example to fit their use case.
• Include detailed workarounds for potential trouble spots.
• Author with lean content principles; that is, get to the point with as few words as possible.
• Add diagrams or screen captures for complex concepts.
• Avoid inline hyperlinks. They create noise and confusion. If links are necessary, add them at the end of an article in a “more information” section.
• Honor search engine optimization guidelines for findability. For example, use unique topic titles and introductions that repeat the title keywords. This tactic helps users find topics using a familiar Google search, rather than navigating through a large website.
• Honor accessibility guidelines. For example, include alt text for images and text strings and formatting that are easy for e-readers to follow.
• Ensure that customer documentation language, branding, and messaging aligns with other mainframe content deliverables, such as UIs, JCL, and PTFs.
• Include a verification step to finish a procedure so the user confirms that the procedure was a success (or not). For example, “Log in to the UI and view the sample workflows to confirm access to the application and its data.”

The FUTURE

We embrace a continuous improvement and continuous delivery model. Therefore, we will continue to look for ways to build upon this strategy and these tactics to help next-gen mainframers be successful. We wish our retiring mainframers well and thank them for their stewardship over this platform and its mission-critical data.