Should user manuals be organized by feature or process?

Question

We have developed a software package and need to write a user manual. I'm trying to determine if the manual should be approached from the perspective of "process" (i.e. accomplishing specific business tasks) or "features" (i.e. the different parts of the system).

The best example of what I mean would be that documenting by "feature" might have a section called "Reporting" that goes through all the reports in the system and what they do and when to use them. When documenting by "process", then the documentation would have sections that walk you through specific business processes. In this case, printing a given report might be listed as one step in a particular process. (i.e. Step 4 of the process X is to print the Jury Summons)

Is there a preferred method or a standard guideline for this?

Answer 1

In most cases, I think, it is best to organize an end-user manual by process because this is what the user cares about. When they use the software they will begin with the first step of their workflow and work according to their process. Complex processes can be divided into smaller sub-processes. The manual's outline will then follow their progress. Users can find help quickly as they should always have a good idea where to look in the manual.

When organized by feature, the users will face a major problem: How should they know what the name of all relevant features for their current problems are? Let me explain it using an example. Imagine the user wants to print a photo and it comes out with a red tint. They probably guess to look up the print feature in the manual, but they might forget to look up the soft proofing feature, since they don't know about it. If the manual was organized by steps, they would have noticed that they went directly from step no. 1 (load photo) to 3 (print) and skipped step 2 (soft-proof).

A feature-organized reference might be helpful to other programmers, e.g. so they can extend your software with a plugin. They usually want to use specific features and combine them with their own code to assemble something new. This is another way of working compared to the end user.

In conclusion, my advice is to have the user's perspective in mind and organize it such that the manual's structure follows the user's process(es). An index with all features at the end of the manual could still be very helpful.

Answer 2

I will echo Matt in suggesting that the process orientation is the best approach.

However, let me propose a hybrid approach. The software might support multiple processes and those processes might share functional steps. Duplicating the documentation for those shared steps (especially if the steps are complicated) is not a good idea. It is better to document the shared functions separately and reference those shared sections from within the process documentation, possibly declaring parameters such as "ignore the snozzle option" and "set the twiddle factor to at least 12" as a part of the reference.

Some other factors to consider are the media for the documentation. There is printed: old school and difficult to distribute and update but suitable for markup and highlighting by the user community. There is PDF: not so old school and not so easy to markup but easy to distribute and update. There are various forms of web pages and Wikis: very flexible, easy to update, and in some cases easy to annotate. Finally, the documentation could be pop-ups embedded in the software itself: more of a pain to update but very handy. Ideally, the designer will consider how the documentation integrates into the overall architecture of the application.

Answer 3

Why not both?

In the Olden Days™, software would often come with two sorts of documentation:

• A tutorial or user guide, explaining how to perform common tasks.  This could be anything from a quick getting-started guide, up to a comprehensive list of tasks you might want to perform.

• A reference manual, giving details of all the software's functions.  It might be arranged by screens, menu options, commands, or however the software was structured; whichever bit of the software you had trouble with, you could look it up.

(Sometimes the two would be combined in the same physical book or booklet — with the tutorial section first, after the introduction &c.  Or for big and complex software, they could be separate.  For very big software, each might fill several volumes!)

Those two are complementary; they're both useful, at different times and in different ways.  A tutorial is good for getting started or learning new parts of the software (before you know which features/commands/&c to look up); a reference helps later on, for filling in the details and helping when you get stuck.

It sounds like you're trying to decide between one or the other of these types of documentation.  Since I think most of the above still applies, I'd encourage you to consider including both!  There tends to be less overlap between them than you might think: the tutorial doesn't need to repeat the nitty-gritty details that are well covered in the reference section, and the reference section doesn't need to motivate or explain what the features are for, just how to use them.

Answer 4

Reading is writing

User documentation falls under the same rules as any other writing; reading is more than half the job. So, you should definitely look into some existing user documentation to get a feel for how they have done it.

By target audience

That being said...

When I document software I always take the target audience into consideration. In your case, it's the end-user. However, end-users aren't a homogenous group.

The biggest difference comes from experience with the software. Is it a user fresh off the introduction course needing a step-by-step description of the process, or is it an experienced user needing to look up some command or other fact?

For the first type of user, it would be best to document by process, maybe even (but this almost falls into training material) in a way that shows the user how to perform tasks/processes with an example set of data ("How to create monthly ABC-reports for company ACME's XYZ..." etc.)

For the second type of user, some kind of command/task dictionary would be most helpful. A good approach I use is to start off with a "quick guide" where you get the bare minimum answering the "how was the command/task performed now again"-question, e.g. syntax descriptions for SQL software, or as a terse list of steps that an experienced user will understand immediately.

After the quick guide, you could add details, discussions about options, further information, references to other parts of the documentation, etc.

Grouped by feature

Depending on the complexity of the software you are documenting it may be necessary to divide the documentation into groups by feature and then for each feature offer both feature type documentation (what reports exist) and process type documentation (how to produce reports).

Very important processes may also get their own "level 1"-heading alongside the features. One example that comes to mind is the introduction to the software, the introduction to the documentation, and the "getting started" section. But most software may also have one or a few processes that are central, important, and/or span several features.

As a complement to training courses

Another aspect of documentation is; should it be a complement to training courses where the user could be expected to already have course material? In this case, you need more reference type material and less step-by-step type.

Creating and offering course material can also be part of the documentation strategy with or without selling a course with it. And selling courses for the software are sometimes part of the business strategy as well.

Other types of helpful documentation

Another type of documentation I find useful is different types of troubleshooting help. As a technical support person, I've built a dictionary of error messages and possible causes and fixes. I feel the software developer could have spared me the pain by just providing it... and spared me the pain of having to divulge that information to the end-user... again... and again... and again... but maybe, that's just me... ;o)

I've also seen documentation that walks through the user interface of the system. This, however, is usually part of the step-by-step documentation, but sometimes I've seen it in the shape of a UI-reference section as well.

Medium

Finally, I think it's worth considering the choice of medium for a bit.

In most cases, it may be possible to convince users to visit a website with a wiki or similar format for information. In this case, the issues of having to repeat information will of course be less problematic, just link, include, or otherwise reuse the digital information.

However, PDFs seem to be the safest bet (unless your program is to be used by the military...)

I've seen cases where security concerns would have prevented or at least severely limited the end-users from visiting the web. So going web all out or as an only option may be problematic.

But this probably depends on what kind of software you're documenting.

In-system-documentation is usually of the "dictionary" type mentioned above and would probably not be a good fit for a new user unless they had good support from training material.