Mr. Procedure Discusses Procedures — Documenting Software (Part 2)

I apologize for the delay in following up part 1. As discussed in part 1, I considered how software might be documented as part of the larger project documenting a task (usually related to the operation of equipment). In such an environment, the software used to control the equipment is rightly described as a control.

Now the question becomes: when the software itself is the focus of the document, to what depth do I discuss the software functions? I would assume that, at some point, every function has to be described. I will go out on a limb and figure every feature of a software program is there because some user will need it, and if that user needs it, I (as software describer) had better provide a description of its use, how to access it, etc. In short, make sure that the user even knows it exists.

As a result, my axiom to ensure I describe everything that needs describing threatens to run headlong into my axiom to support the adult learner in acquiring information. As a result, my outline to develop a software guide is going to be structured something like this:

1. Introduction to the software (describe its basic abilities, what it does or can do at a high level; explain why the software even exists)

2. General outline of the features (major screens or menus, their function)

3. More specific discussion of features, in which the features will be connected to the basic and intermediate tasks a user of the software would perform

4. How to perform basic tasks (set up, enter data, review data, save data)

5. How to perform what may be termed intermediate tasks (more advanced than basic)

Sections 2-5 would collectively cover what I would call “Layer 1” of software usage. Assuming the user learns and masters the content of Layer 1, subsequent sets of sections can discuss subsequent layers (the number of layers would depend on the complexity and/or capabilities of the software itself).

As for dissecting individual features, I would attempt to limit my discussion of features, initially at least, to those actually used in the tasks described. But further on, separate from the layered discussion above, I would have as needed detailed discussion of the other functions. Each I would attempt to set up as follows:

     Name of feature

     What the feature allows the user to do

     Access and use of the feature

     Other features associated with this feature

Since a lot of these features would most likely be accessed by an index, I would want the user to see right up front what the feature is intended to do. If the feature does not do what the user is researching to see if the feature does, the user should understand that right away instead of after spending several minutes reading about the feature and playing with it.

Anyhow, that is my take. As I wrote this, I did not have a specific type of software in mind. Again, I have not previously written software descriptions except for cases where the software was part of the equipment’s control system. My thought process is based on the idea that the organization’s needs (what they need done) is the independent variable and the software capability (how the software accomplishes what the organization needs) is the dependent variable, as opposed to the other way around. That is, the organization has task-related needs to have the software they have purchased, and their first priority is getting those tasks accomplished, not learning some cool new software. I may be completely wrong in that assessment; maybe to the software developer, the software is “the thing” and the user is expected to rearrange their operations to fit into what the software supports.

Of course, thinking of my experience with ERP (enterprise resource planning) software, I may be spun 180° around in my thinking. This is where I expect those of you with more experience and understanding to comment back to me. Just be nice about it.

Advertisements

About Tim James "Mr. Procedure"

A communicator; all-purpose capability in writing, designing and presenting training for all facets of organizational function. While my focus has been manufacturing, my training/development experience includes supervisory and lead person development, audit processes, continuous improvement and Lean, and Quality Management System implementation.
This entry was posted in Uncategorized. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s