Challenges From a Failure to Document: The iSeries System

The computing world is always changing, from new programming languages to advanced hardware. Companies like Intel and AMD come to mind when the word ‘innovation’ is used. However, many large corporations still use older systems for their ERP and database functions.

So why use older systems if modern solutions offer better performance? In a word, reliability. Around 75,000 companies still use IBM AS400 iSeries instances because of their time-tested performance.

However, the coding world was very different back in the late 80s and early 90s when the AS400 first entered service. As a result, many of the programs used today are woefully under documented. Keep reading to learn about the challenges this presents to programmers and IT departments servicing the iSeries range.

Introducing the AS400

IBM unveiled the AS400 system way back in 1988 as a midrange solution for businesses to manage functions like ERP and databases. In the two decades that followed, IBM evolved the platform into the iSeries and POWER lineup, retaining backward compatibility.

Because the underlying programs and OS on the AS400 are hardware agnostic, they can be migrated to newer systems with minimal overhead. With IBM’s backward compatibility, the foundation was set for immense longevity.

As a result, many companies still rely on applications designed decades ago. If it’s not broken, don’t fix it, right? Unfortunately, that’s not always the case.

Setting the Foundation for Challenges

Program and software engineering are very different in today’s environment. When the iSeries AS400 first launched (before it was even called iSeries), many of the concepts used in modern SDLC didn’t exist.

The industry was in a different place and time, and many lessons were still learned about best practices. Concepts like data security and what can access certain bits of information were part of the industry, but documentation and code readability was not.

If you’ve ever worked on legacy code, you’ve probably run into a lack of documentation. Even modern codebases struggle to maintain detailed documentation. So why is documentation so hard in the first place?

Lacking iSeries Documentation Challenges

IBM provides excellent documentation for the operating system and hardware. Program documentation is on the businesses using them. However, it’s taken a back seat, with many not understanding its importance. 

Training Issues

Training new developers is hard without proper documentation. It increases their time to understand the codebase and begin maintaining or updating features.

Reduces Future Changes

Without knowing what functions or the program is doing, it’s difficult to understand where future changes are needed. Businesses spend time and resources evaluating pain points so they can reduce overhead. Without documentation, this becomes almost impossible to do.

Long Resolution Times

Resolving customer or internal tickets is a crucial part of operations. Without documentation, tracking the cause and resolving the issue becomes hard and consumes additional time. This lowers productivity and makes it harder to put out fires as they crop up.

Upgrade and Maintenance Difficulty

Upgrading and maintaining codebases is a key part of the SDLC. Without documentation, this process takes longer as engineers need to understand the ins and outs of the program. Even simple changes require more effort to ensure the program is functional.

Program Use

Many applications are still operating in a ‘green screen’ or terminal-style format. Code isn’t the only area that needs documentation. Proper use documentation for program users is necessary until a reskin or GUI is applied to your application.

Documentation Difficulty

Even with modern procedures for SDLC, documentation is a difficult task. What makes documentation hard for programmers and software devs?


For proficient software engineers, writing code is like fine poetry. Those documenting it may not see it as such, however.

Documenting procedures or tasks is a linear process, but code is often not linear. This requires writers to move about throughout the entire codebase to understand it.

Audience Variance

Another difficulty is writing to a wide audience range. Experienced devs will need less in-depth documentation or can understand advanced language and principles. Junior devs or other documenters will need more information and simpler language.

Good vs. Bad Code

Engineers will have a keen eye for good code and can tell when code is bad. Those working to document it may not have such a developed eye. Even if bad code is documented well, it’s still bad code.

Benefits of iSeries Documentation

A lack of documentation presents serious challenges for any iSeries system or AS400 software. However, you may be wondering what exactly the benefits would be. Keep reading to find out more!

Resource Utilization

Transfer of knowledge occurs anytime you’re training new staff or attempting to understand why something works the way it does. With proper documentation, the time necessary for this is vastly reduced.

It also reduces the burden on your engineers and IT departments in the event of a problem. They’ll be able to work through the code and understand what’s going on much quicker.

Outside Understanding

Software devs aren’t the only ones to benefit. Anyone involved in decision-making processes regarding the codebase or features will benefit from understanding what’s going on under the hood.

Reduce Confusion

As mentioned above, code is often non-linear. Understanding a function or figuring out a particular section may require a lot of cross-referencing throughout the codebase. Proper documentation of AS400 software allows devs to understand functions without referencing other areas.

Improve Your Business

Working with iSeries doesn’t have to be hard. You and your team can focus on what really matters and spend less time in frustration with proper documentation.

Whether you need a professional with legacy programming or are looking for other resources to help you out, we’ve got you covered. Contact us today to see how we can help you and your business, whether you’re using an iSeries system or not!