Have you reflected on what type of information you include in a manual? Meaning, for whom are you designing and writing? Your manual(s) contains certain type of information, but who needs the information, when, to do what? This blog post tries to sort it all out. Read it to find out what type of technical communicator you are.

Consider a company developing a software product. Let’s call the company “X” and the software product “Y”. The software Y needs documentation. A technical communicator within company X is making the documentation for software Y. Let’s call him or her “technical communicator Z”. Software Y from company X is purchased and used by users, the customers.

The users/customers can be an organization (B2B) - let’s call them “company A” - which uses the software Y to achieve certain goals within the organization. Maybe as a part in a process chain to develop and manufacture specific products, sold on a specific market. These specific products also need documentation, but the documentation for software product Y doesn’t have anything to do with the documentation for these specific products. There are many companies of type A, each one slightly different, having its own way of using software Y.

Another type of users/customers for software Y - let’s call them “company B” - is an organization that integrates the software Y into a larger system. The system is then sold and delivered to an operator, for example when a nuclear plant is delivered to a power company, responsible for operating the plant. Software Y is then configured to suit the specific plant delivery. This means that the power company is using a configured version of software Y. There are many companies of type B, each one using and configuring software Y slightly different.

Consider the users of software Y in companies of type A and B. In companies of type A or B, the software Y is used in a certain way by certain users having a certain role. Each company A or B have their own set up of users and each company is using software Y slightly different. More important, the users have an agenda, responsibilities and goals within the organization. They need to carry out their work in a professional manner. It means having the competence of knowing what is important and not important, how to best execute the responsibilities, how the tasks that the responsibilities implies at hand are carried out, meaning where start and how to proceed. The software Y is one part of the daily life of users in companies of type A or B.

And here is the catch. The documentation for software Y provided by technical communicator Z in company X shall not describe how users in companies of type A or B shall execute their responsibilities. An individual having a role in company A or B is probably not looking in the manual for software Y to find out how they are supposed to carry out their duties within their organization.

Imagine you are the technical communicator Z in company X doing the documentation for software Y. If you follow the user centered design approach, you start by identifying user groups, their tasks and responsibilities and the environment in which the tasks are carried out. This approach is clearly stated in “IEEE standard for Adoption of ISO/IEC 26514:2008, Systems and Software Engineering – Requirements for Designers and Developers of User Documentation” (issued January 2011). In section 7.1.1 on page 25, regarding how to carry out audience and task analysis when designing planning and designing software documentation it is said:

“The designer shall list the intended types of users of the software product and classify users into audiences. Each audience consists of a group of users whose work tasks and use of the application are similar.”

On page 28 it is stated that “The documentation designer should collect information about what users do, if possible by asking users questions, or by observing users and recording what they do.”

What does this mean? The risk is that you might end up in making a manual that addresses the daily life of a specific user in a company of type A or B. Do you really want to tell your users how they should live their life? That is not your intention or?

If it is, I guess you have a lot to do since there are not a homogenous set up of roles among users of technical products. You need then to create a manual for each user role in each possible customer company. The task to interview and document the daily life of these users is a huge task. Maybe you are aware of this fact and as a consequence you simplify the analysis and generalize it to make a set of manuals based on a generalized and summarized role description. Is this a good way of designing documentation? Doing role based documentation that doesn’t match anyone?

Identifying users and categorizing them into groups, where each group is described as a persona is a good design practice when a new product (hardware, software, internet site etc) is to be designed. The targeted users have certain characteristics and the new product shall be designed to support the users, given the ability they have. The user groups are merely a tool for product design. The division of user groups is often not visible in the final product. For example, have you ever seen products being packaged according to an assumption about users? Consider making several version of MS Word: “MS word for call center operators”, “MS Word for call center supervisor”, “MS word for warehouse manager”, “MS word for finance manager”, “MS Word for accounts manager”. Which version would you choose?

Maybe you are a technical communicator in a company of type A or B, responsible for creating instructions on how different products, including software Y, shall be used within the company. And also creating instructions for how different roles within the company are supposed to execute their responsibilities. But such a technical communicator has a different focus than the technical communicator Z in company X. A technical communicator in companies of type A and B may reuse the documentation created by the technical communicator Z in company X. The technical communicator in company A or B extends the documentation for software Y to give the specifics of how software Y is configured/customized and supposed to be used within the company A or B.

How should technical communicator Z design the documentation for software Y? Let’s take a step back. Companies of type A or B are sometimes facing a problem, need or requirement. They might want to optimize or automate a process, make a production process more secure or cost efficient, reduce cost of ownership for manufacturing equipment etc. This equals their primary goals. They investigate how to solve the primary goals and maybe the answer is software Y. Companies of type A or B are buying software Y because they believe, maybe since they have read the manual, that the software Y can solve their primary goals.

The documentation for software Y must reveal what results the software can deliver to solve what primary goals. The secondary goal for companies or type A or B is then to get the software Y to deliver the results that solves the primary goals. So the documentation for software Y must give the instructions about how to use software Y to allow user reach the secondary goals and in turn the primary goals. As a technical communicator Z in company X you must focus on the product (software Y) and provide information about what problems, needs or requirements (user primary goals) the software Y is solving and how to use it (user secondary goals) to solve the primary goals.

So for whom are you designing? Are you a technical communicator in companies of type X, making documentation for the products your company is developing? Or are you a technical communicator within companies of type A or B where the target group is your colleagues or customers buying a complete delivery? I argue that the user centered design approach, cemented in standards such as IEEE standard for Adoption of ISO/IEC 26514:2008, is not allowing you to create documentation that is usable or gives good findability. You need another design approach such as SeSAM.

SeSAM is the design methodology you need as a technical communicator in companies of type X, to design documentation for products such as software Y. Maybe this blog post sounds like SeSAM is not taken different types of users and their information need into account. On the contrary my friend (find out by yourself). But, SeSAM is not targeting technical communicators in companies of type A or B.