A Better Run Control Page Standard

Run control pages can be hard for users to comprehend. When a user looks at a run control page they may ask:

• What is this process and what are the ramifications of running it?
• If I run this process, does it update data that cannot be reversed?
• Does this process produce any output? If so, where can I find it?
• The process error-ed out, what should I do?
• What happens if I choose option x over option y?

These questions can occur as a result of:

• Staff turnover and reorganizations.
• The process is run only periodically
• The process is new to the user because of a security change.

Several outcomes may occur when a user is confused:

• They do nothing.
• They start a process without understanding that the results cannot be reverted easily.
• They open a support ticket.
• They complain to their manager and say that “the system is horrible.”

If you give the user information they need at the time they need it, you can attain many positive outcomes.

• A better user experience
• Lower cost of ownership from decreased support tickets
• Empowered users

How can we accomplish this? First, take a look at this article Making Pretty Page Text with HTML Areas.

Let’s take the “pretty page text” idea and implement a standard for run control pages.

Here are some recommended sections to include on every run control page.

• Introduction

  • Give a brief description of the process as if someone who knows nothing about the process would understand it
  • Include any assumptions like dates or dependencies on other processes
  • Include any gotchas about the process
  • Is any special CI or other security required?
  • Can it be run more than once a day or for the same parameters?
  • Document any message catalogs that are used in the process for stuff like emails, reports or logs.

• Inputs

  • Explain each parameter and what they mean in the program
  • Document if they are optional or required

• Processing

  • Include some notes about what kind of data is processed
  • Include SQL where clause criteria along with “plain language” for non-technical people.

• Outputs

  • Does the process produce a file? Where does it get written two?
  • Is a log table populated? What is the table name or relevant query or report name for that log?

• Troubleshooting

  • Include common troubleshooting tips for the process
  • What happens when it errors out