Planning out your documentation

Earlier this week I tweeted this:

Normally this would be a dig on someone else, but in this case I was actually digging on myself. I had just wrapped up a 2 hour session of going back and forth with a remote employee on how to use a new report in Maximo. The steps I gave I thought were quite clear:

  1. Log into Maximo and go to Inventory application.
  2. Search for inventory items that need to be printed on labels - e.g. all items in a specific bin.
  3. From the 'Select Action' menu, Click Run Reports and select the "Inventory Bin Labels" report.
  4. Run the report and export results as a PDF. Leave all the other settings as is.
  5. Save the PDF file to your desktop or preferred file folder.
  6. Open the PDF file and print at 100% scale on label sheets. Do not print at 'Scale to Fit' or 'Fit to Page'.

The problem was I thought the directions were clear. I was the one who created the workflow to run the report to print out the results, I was the one who troubleshooted the process for the step by step procedure, and I was the who sent out the documentation to other Maximo users.

Since I was the one who did all the work, I was the only one who knew exactly how to print the report.

Looking back I realized I didn't do this coworker any favors by rushing out an abbreviated step by step procedure. I took a step back and created another set of directions. This time I followed my standard practice for creating Maximo documentation:

  1. Outline the steps: From beginning to end, collect all the steps needed to do the task you want to document. Don't worry about the details, just make sure you got down everything. This includes some of the simpler steps like what module to go to and any steps you assumed a user would take.
  2. Fill in the details: Now go back to the outline and fill in the details. This is where all the minor steps and potential 'gotchas' should be documented - what button do you need to push, what button should you not push, etc. Use screenshots to emphasize where/how a certain step is supposed to be taken.
  3. Try it yourself: Go back a third time and do all the steps yourself... exactly as you wrote them. This is actually the hardest step because it forces you to turn off what you already know. Go step by step and see if you can repeat the process based on what is written down, not what you know. If you can't, go back to step #2 and re-document the process. Try again and again until you can get the desired results.

After reviewing what I had originally sent out, versus my 2nd version, I realized that I had not cleanly explained how to export the report to a PDF. Most of my Maximo users have the option to print to PDF from an application. So in this case, the Maximo user used the browser's print function to print the web page the report generated to PDF. After sending the 2nd version of the step by step process the user had no issues getting the report to print new bin labels.


Brevity of how to do something has never made for better directions.

Comments

Top