Reader Response: Structuring Complex InstructionsHeroic Technical Writing: Advice and Insights on the Business of Technical CommunicationHeroic Technical Writing: Advice and Insights on the Business of Technical Communication

Today’s post is a response to an instructor friend’s response to my call for topics (Reminder: I’ll take them from strangers, too!). Jane’s initial question was: “Do you have anything on there on how to structure complex sets of instructions?” I will now. Let’s dive in!

So What’s the Problem?

Here was Jane’s full query:

Do you have anything on there on how to structure complex sets of instructions? Like nested and extremely varying data and how to present it so that it looks somewhat sane? Maybe some philosophical principles for structuring that sort of thing? [My students are] just working with a client to create a major manual. The students are doing a 75 page manual for the back end of bring [X website] and they are having some issues just representing a lot of data tables and nested instructions (there are a lot of status states in the instructions for some reason, so I’ve asked them to talk to the developers and see if what they are representing is accurate), but and I’m not seeing a lot of nuts and bolts stuff out there for how to represent the sort of complex information. I think because it’s always individual, but, what is the best way to present multiple forms of data?

Back to Basics

Let’s start with the basics…which, oddly enough, is how I’d structure this particular section of documentation. Any software system is going to have a standard set of operations, which are driven by the user needs. On a retail website, for example, common functions might be:

Making one or more purchases
Requesting a return
Send a message to customer service

In my mind, the best way to get the reader (end user, programmer, etc.) oriented is first to present a simple, ideal case–say, you’ve got an order for one item. For amusement’s sake (and because I’ve got a sweet tooth), let’s use the Wonderkeks cookie company’s site as an example.

On a simple order, a customer might want to buy half a dozen of their classic chocolate chip cookies. That’s one item, with only one type of item included.
A slightly more complex order might include multiple items, such as half a dozen of the chocolate chip cookies plus a care package with a dozen inside-out cookies.
A complex order could include the above plus a care package with multiple types of cookies (also an option, I checked! 😉 ).

While these sorts of transactions are relatively straightforward to the customer, a programmer will face a few challenges because they have to handle multiple variables that all must come together to create a correct order and price in the shopping cart at the end. They are therefore combining:

The customer and his/her information
The specific transaction
The individual products within the transaction
- The types of products purchased
- The quantities of each product purchased
- Variables within the products purchased, such as the types of cookies sold within each
Prices for each item
Taxes for each item
A calculation for the entire transaction
A command to generate an invoice accurately displaying all of the above

While most of the items in the bulleted list are straightforward, the product portion will require a few extra bits of coding gymnastics because a transaction is a variable that changes with the number of items purchased (another variable) and, potentially, their sub-products and prices (a set of related variables). This is (I believe) what Jane meant by “nested variables.”

Again, it’s best to start with describing how to develop the simple cases first, then work down into the more complex activities: single-item purchases, multiple-item purchases, multiple-item purchases with options. And let’s say for argument’s sake that individual cookies are priced differently from batches. You’d have one table of values (the table where the point-of-sale program would draw its dollar values from) for the batches and a different table for the individual cookies cost if they are included in a “care package.” The table of values would appear in the documentation as they are needed: the batch prices in the simple use case, the individual prices in the multiple-items-with-options use case.

Bottom line: It’s best not to overwhelm a user or a programmer with every if-then statement that could possibly appear in the first section of your instructions. Start simple, and then move forward into the more challenging cases, much as you do in math classes.

Clear as cookie batter? Great! Now I’m hungry.

Update 23 November 2020

I was crushed to learn, after further review, that you cannot, in fact, customize the cookies within a care package; you can only purchase one flavor. : ( That said, I still expect them to be delicious.