Information to Place in the Main Flow of Content

Friday, April 10th, 2009 | Design / CSS, Technical Communication

The main stakeholder for one of my projects has asked for a procedural user guide for certain tasks in the application performed by particular user roles. It will be comparable to a manual I did for another application for the same stakeholder; that one was organized first by role and then by task. The business process was heavily intertwined with some of the software procedures in that manual. This next one may be the same way, though it won’t be as substantial a project because not nearly as many tasks will be included.

In that previous manual, I had a side column for note boxes, but the rest of the information was contained in the main column. Many different kinds of information were mixed in that main flow of content, with only some being set off by some style or another. I think that’s a bit problematic. Users wouldn’t be able to tell readily which type of information they happened to be looking at all the time.

Apparently, the previous manual was a good format overall because it could be handed to new users partly as a description of job responsibilities. I also saw one user had written in the side column. That particular user group is used to having things in hard copy.

I’ve considered having two columns again, maybe a two-thirds / one-third format, and better defining which kinds of information go in which column.

These kinds of information would go in the main flow:

Concepts essential to completing a procedure
Setup or preliminary actions needed
Instructions for completing the task
Warnings (things the user needs to know right now)
Screenshots and diagrams

Types of information I would place in the second column:

Concepts not essential to understanding or completing a procedure
Examples of how the user would follow the procedure in a hypothetical situation
Notes, reminders, or other secondary information
Cross references

Then I would set the different types of information off with different styles to make them more recognizable at a glance.

The dilemma I’m struggling with is not spending inordinate amounts of time worrying about styling. My colleague suggested I just write the content in my help system and generate the user guide from there, excluding that content from the online help. That way, at least I would have all my content in one place. But then I would need to style the Word template used for mapping styles in the print output.

I think what I’ll have to do is write the material and then decide whether there are enough different kinds of information that I need to break them out. If everything is relatively simple (I know it won’t be as complicated as the previous manual), I’ll just run it out of my help project.

Share This