One of the things I use to make a point about the programs I modify is a simple screenshot. Why? I use screens, the users use my screens, we all use screens. There's no better way to illustrate what you've done.
Taking a screenshot is possible without purchasing a software package; however, the image is quite large and represents only the what, not the why, of our documenting equation. That's why I use Snag-it by Techsoft. There are other packages on the market that perform relatively the same function, but this one has the most features, including screen video capture and annotation of images using easy-to-use tools.
Let's take a look at how you can use screen shots to improve your documentation.
Step 1. Start your documentation
First, design several word processing templates for your most popular patterns:
- Creation of a new function
- Creation of a MODIFICATION of an existing function
- Designing a new system
- Drawing up SPECS for any of the above
You need an overview of the thing you're doing. Someone probably needs to approve your project -- will this document have tremendous impact? Can you make SURE it has tremendous impact?
Step 2. Capture some screenshots now
Show what everything looked like before you started.
Figure 1: The user wants the final menu removed
Did you all say, "Dull lifeless and boring?" You are correct. Had I used a standard screenshot, it would have looked like this:
Figure 2: Standard screen shot
You get a border and a status line. But does the user see what you NEED him to focus on? Lets figure out what we want by illustrating that a picture is truly worth a 1,000 words.
Figure 3: Revised screenshot show the modification requested by John Doe
It's clear what the modification was and who asked for it. But this is a modification. Why not show an after image?
Figure 4: What it looks like after the modification is made
Step 3. Documenting your changes -- who's your audience?
Who's going to be READING what you're writing? Programmers? Users? CEOs? There's a big difference in how you approach each group.
Documenting for programmers
If you're writing for programmers, document the REASON you're doing something, not necessarily WHAT you're doing. Here's an example:
Lookup record for Customer -- returned value of John Doe when customer not found.
What was wrong?
- It's WHAT is happening, but WHY is far more important.
- It was in code-ish (that's English merged with CODE) -- NOT English.
- Since it documented WHAT was happening, the programmer KNOWS that's what those lines or that line does.
This documentation is better:
Per the Marketing department: When adding new customers, and their name is not found, use John Doe as the default customer name!
- It was in English instated of code-ish.
- It gave reasons and their outcome, not just what was happening.
- It used "per" to find out WHY something is happening, it referred to the BUSINESS rule that caused it to happen, and it showed us WHO requested. So, if you have any questions, call the marketing department.
Documenting for users
If you're documenting for users, you need a different approach.
Use lots of examples and screenshots to make your point. Make sure to annotate them with WHERE they need to focus their attention, what they need to enter, and why they are doing it.
Figure 5: You want the user to enter 1 to send the spool file to a remote system or user
That looks boring. How about this instead?
Figure 6: Modified screenshot provides more details, but you could do better
Questions remain, though. Where should the user put that 1? You can focus on the region a little more and get the readers to meet you half way. In the documentation, give them the specific steps to take.
Example:
Step 1. Sign on to the iSeries
Step 2. Type WRKSPLF *ALL
Step 3. On the printout you'd like to send, type 1 and hit Enter (see figure below)
Step-by-step instructions with illustrations -- very cool. Yes, you can write well-written documentation; you just need to break the functions down into their smallest components and capture as many images as you need to get your point across.
Snag-it is a magnificent program that can help you get the images you need. To learn more about the product, go to http://www.techsmith.com/products/snagit/default.asp. Now, back to documenting!
-----------------------------------------
About the author: Andrew Borts is webmaster at United Auto Insurance Group in North Miami, Fla. He is often a frequent speaker at COMMON and is past president of The Southern National Users Group, an iSeries-AS/400 user group based in Deerfield Beach, Fla.
