Valuable Documentation; Do More With Less

Valuable Documentation; Do More With Less

Does anybody read the instruction manual?

The answer is "No," almost no one reads the manual, especially new users.  (I don't read the manual either.)

Still, good documentation is highly valuable to both new users and advanced users of a tool.  (tool = software or equipment or machine, etc.)  The best documentation is easy for the writer to write and update, provides simple instructions for new users, and gives access to detailed explanations for advanced users.  How do developers help users learn tools, and focus our documentation effort on what's useful for advanced users?

In the early years of my engineering career, I wrote a tool to calculate impedance.  It was a spreadsheet-based calculator that collected, in one place, characteristic impedance formulas for co-ax, microstrip, stripline and a few other structures.  I shared it with some other engineers and there were a lot of questions about it.  So I spent many hours documenting it, using screenshots and explanations, detailing every equation used and writing about how to use the tool.  The documentation effort consumed many times more hours than the writing tool. The tool took about 8 hours to build, while the documentation took about 40 hours.  After sending out the documentation to the users, it was clear that the documentation was a failure.  There were the same number of questions and same amount of confusion as when I had zero documentation.  The documentation Was not a good use of my time.

Basically, people asked two types of questions:

TYPE-1:  As a new user, how do I use the tool quickly to get results?

TYPE-2:  What exactly is the tool doing and are the results correct?

I thought I had addressed question 1, by explaining the entries in the spreadsheet and showing some screenshots.  The problem was that the information was methodical, but disorganized and didn't have a story or workflow.  After rewriting the documentation to highlight workflows and recipes for the most common tasks, the number of questions from new users dropped by about 75%.

For question 2, I thought that showing the formulas and calculations was sufficient.  I learned that engineers like to see comparison to known reference data (usually measurements) and like to see acceptance from other experts.  For the closed-form equations, I added references to the textbooks and papers where they were published.  I also added one example of a highly accurate simulation, compared to the results of the tool. 

(Side note:  When doing a tool accuracy study, I recommend doing one and only one example.  Doing more than one has vastly diminishing returns, because accuracy studies are so time consuming.  References, comparisons and one example is sufficient for almost all users.  For the one or two users where that's not enough, a one-on-one discussion works well.)

After updating the documentation, the number of type-2 questions dropped by about two-thirds. 

Here are some guidelines for spending a minimal amount of time and generating useful documentation.
There are three and a half purposes for documenting something:

1. Help new users start using the tool effectively.

2. For advanced users, provide detailed explanation of what the tool is doing and how it works.  Also advanced users want to know how to do some exact task that they can't figure out and how to do complicated, high-value, less-common tasks.

3. Share information between developers so they can improve the tool and update the documentation effectively.

3.5  When the manager says "Is this thing documented?"  Allow the engineers to reply "Yes, of course!"

There are many typical problems with documentation.  Here are some negative scenarios to avoid:

- People spend hundreds of engineering hours writing a 200-page instruction manual, then nobody reads it.  Users contact customer support with every question.

- New users look for information on how to use the tool, and either can't find the documentation, or don't understand it.  Perhaps they start reading it and give up because it's too long / annoying to read / is too complicated.

- Advanced users want to know how something works or want to do some advanced tasks.  They read the documentation and can't find the explanation that they need and can't figure out how to do the task they're trying to do.

For new users, the best documentation is a well-designed tool.  Users can start using it intuitively; the default settings do something useful and informative.  Also, have a step-by-step tutorial that doubles as the test plan.  Do this in detail, including example inputs and expected outputs.  You can give this to anybody and they can test your thing.  It also helps you, the developer, to remember every test step.

For advanced users, two main things are needed:

1. Searchable index of all features of the thing so users can find and use that one powerful feature they need and can't quite figure out.

2. Explanations of the unique, novel features of the thing.  Basically, try to anticipate questions and explanations that a highly experienced engineer would want to know.  For instance, a tool that plots s-parameter results doesn't need much explanation for plotting magnitude and phase.  It just reads values directly from the s-parameter and plots them.  On the other hand, for the within pair differential skew results, a detailed explanation is needed.  Advanced users need to know exactly how skew is calculated in order to understand the results.

It's often good to avoid using pictures.  A picture is worth a thousand words, but costs a hundred revisions.  Every time something changes, the documentation needs to change. Changing a picture takes 100x longer than editing a few lines of text.  Plus, text is a universal format; it works on computers, mobile devices, email, etc.  Many pictures in documentation are outdated and don't match the tool anyway.  Thus, I recommend avoiding pictures in documentation, it just takes way to long to create and maintain the pictures.  Using 100% text is so much faster to document than anything with pictures.

GUIDELINES FOR DOCUMENTATION TEXT

1. Write and update the documentation text so it matches exactly with thing.  For instance, with a save button in a tool, use the same upper and lower case and same words in the documentations as in the tool.  If the button reads "Save File" then the documentation should read "Save File" not "save" or "SAVE FILE."  Use consistent formatting, such as quotes or brackets or bold font, to highlight that the documentation is calling out a label verbatim from the tool.  Whenever a tool label changes, update the documentation so that it matches.

2. Draw simple text pictures to help the user understand.  For instance, tell the user what happens when the "Save File" button is pressed.  Draw an asci text picture of the button:

__________
|                   |
| Save File   | <--- Press "Save File" button and results are saved to a .s4p s-parameter file.
|_________|

Here's an example of how to make useful documentation without too much pain and time. S4PTOOL is a general tool for viewing, plotting and making reports from s4p s-parameter files.

SNAPSHOT OF S4PTOOL

The documentation text window pops up when the user presses the "?" button next to the 

“S4PTOOL” title.

>>>>>>>>>>   S4PTOOL DOCUMENTATION   <<<<<<<<<<

What this tool does:

   This tool is a general purpose .s4p viewer tool.

   This tool takes one or more .s4p files as inputs, and generates 4 plots on the screen, based on the current plot settings.

   Plot setting include differential or single-ended, magnitude or phase, and port configuration.

   It makes a report using powerpoint slides.

How to read this help file:

   People who learn by experimenting can stop reading now and just try the tool.

      The tool is designed to be intuitive and simple.  Select File(s) -> Plot Graphs and try a few settings.

   New users can go through the "S4PTOOL Step-by-Step Example" to learn how to do the most common tasks in the tool.

   NOTES FOR ADVANCED USERS section has a few explanations and notes about advanced features.

   COMMAND LIST is a description of commands in the tool.  This is especially useful when searching for specific features.

>>>>>>>>>>   STEP-BY-STEP EXAMPLE   <<<<<<<<<<

*** EXAMPLE FILES ARE FROM THE TOOLSEXAMPLES DIRECTORY ***

https://....toolswebsite.com/Tools/Examples

Read version at the top of the window     :  Is it the latest version 1.0?

Click "Select File(s)" -> Choose Data1\*.s4p (all .s4p files)     : Observe the passivity warning, which is very common with measured files.

   The message window should show "Files loaded!" when the loading is complete.

   HINTS AND TIPS:  Rt-click on the Current Folder entry of the select files window to access a history of recent directories.

Click "Plot Graphs"     : Observe viewer plots

Enter "1" in "Min. Freq..", Enter "20" in "Max. Freq.." -> Click "Update Range"

Choose "Single-ended" -> click "Plot Graphs"    : Observe viewer plots

Choose "Phase" -> click "Plot Graphs"     : Observe viewer plots

Choose "33,34,43,44" in Matrix Section -> Choose "Differential" -> Choose "Magnitude" -> Click Plot Graphs

      :   Observe plot results (Typically this is common mode performance)

Click Autoscale checkbox to turn off automatic scaling and enable manual plot axis scaling.

Enter "-30" in upper left "Min Y"   :  Observe viewer plots  (This changes the y-axis for the upper left and lower right plots, typically 11,22 reflections.)

Enter "-5" in lower left "Max Y"    :  Observe viewer plots  (This changes the y-axis for the lower left and upper right plots, typically 21,12 thrus.)

Observe "File Port Impedance:" label, this shows the .s4p port impedance

Click on lines in each plot to remove them and focus on the remaining lines   : Observe how the plot changes

Click "Show Legend"     : Window pops up showing plot legend; the file related to each plot line color.

Click "Create Report"   : Powerpoint slides are generated with one slide for each of the 4 plots

      NOTE:  Observe slides and check that plots and legend are as expected.

      Save slides to desired filename.

>>>>>>>>>>   NOTES FOR ADVANCED USERS:   <<<<<<<<<<

> The tool plots unwrapped phase, in radians, by taking the unwrapped angle of the complex values in the s-parameter entries.

> For magnitude, the tool plots dB = 20*log10(abs(complex value)) in each s-parameter entry.

> If the user loads .s2p files, the tool builds differential results by copying the .s2p file to ports 3 and 4.

> By clicking on lines in the plot, the user can remove lines and focus in on the remaining results.

>>>>>>>>>>   COMMAND LIST:   <<<<<<<<<<

AutoScale checkbox

   On (default) allows the plot to autoscale the y-axis to the values in the lines plotted.

   Off uses the manual min, max values entered by the user, to define the y-axis range. 

      The upper min, max entries define the upper left and lower right plot ranges. 

      The lower min, max entries define the lower left and upper right plot ranges.

Create Report

   Press the Create Report button to create a powerpoint report from the current plots. 

   The powerpoint will have a title slide, a legend slide showing the file names, plus one side for each of the 4 plots.

   After the slides automatically open, the user must save the powerpoint file to the desired filename.

Error Message: "At least one file violates passivity. Check before continuing."

   If the energy from all ports, at any frequency, is greater than 1, this error pops up.

   This is common for measured low frequency points, such as 10MHz.

   It is the user's responsibility to interpret the plot results carefully.

. . . OTHER COMMANDS

Alphabetical, searchable list of commands, with a few sentences of description for each command.

. . . OTHER COMMANDS

<Question Mark Picture> [?] = Help button;

   Click on it to display help text.  If you are reading this, you probably already clicked the help button.

Select File(s) button

________________________________________

|                                      |

|         Select File(s)               | <--- Press "Select File(s)”

|______________________________________|

   Click this GREEN button and a window opens to choose the file(s) for plotting.  The default File Filter is “*.s*p” to find all s-parameter files.

      The tool supports .s4p and .s2p files. 

   The user may change the filter to *.s4p to choose only s4p files.

   There's a regular expression search, “Reg. Exp. Filter,” to filter file names further.  A simple filter of “test” will search all filenames case-insensitively with the string “test” anywhere in the name. There are multiple ways to choose a directory.

      1. Type in a directory in the Current Folder entry.

      2. Navigate from the current directory to another one using the directory pulldown, or the up directory arrow,

         or going down a directory by choosing a directory under the current folder.

      3. Rt-click in the Current Folder entry to choose from the recent history of directories.

   There are multiple ways to choose a file:

      1. Double-click on a filename.

      2. Left-click on a filename, then click the Add-> button.

      3. Shift-click and/or control-click to choose multiple files, then click the Add-> button.

   After choosing the desired files, click Done.

Show Legend

   Press the Show Legend button to pop up a window that shows the files used and the plot colors and styles for each file.

>>>>>>>>>>>>>>>>>>>>

The documentation above took about 2 hours to write, and takes about 10 minutes to update when the tool is revised.

So, the next time you have a tool or need to write documentation, try these guidelines.   Use all text, have step-by-step instructions for new users and for testing, and have some references for advanced users.

It only takes a few hours to write and it's easy to edit.  You might even use the documentation yourself!