Notes from the Field: Some thoughts on audience and context in software development and user assistance

By Rob Pierce

Many aspects of technical writing, usability, and design continue to rapidly evolve for software development companies. While there will always be theories and practices supporting the field of “developing quality content” for the field of technical communication, the speed at which new user technologies, content types, and user contexts are designed, developed, and delivered races onward. This has been and continues to be challenging, intimidating, yet above all compelling to this particular practitioner.  In this article, I want to address two areas of interest – audience and context.

The software technical writing program I attended 14 years ago focused on “knowing your audience,” structuring content in a logical manner, and not using passive voice. These are all still useful and important lessons but do not nearly represent what is needed in today’s world.

As a technical communicator, you may think of your audience as readers but more likely you think of them as users. What kind of users? We are not thinking in terms of culture, age, or subject matter but rather role and context. Use cases that describe how to do something require an information hierarchy for a logical design for the point or points of entry to information, findability of the right information when people search for it, and a clear picture of the sequence of tasks, topics, and concepts to complete their objectives.

So, what kinds of roles and contexts are we thinking of and who is filling the roles and working in these contexts? For many organizations, we think in terms of customers. Users represent customers installing, configuring, customizing, deploying, and using the software. We also may think of internal customers, colleagues in our organization, who, like external customers, may fill the same roles and contexts and require the same kinds of information.  But audience types are far more diverse than this simple notion of internal and external customers.

What is an admin?

Let’s consider the administrator role for a software product. What administration tasks are mandatory? Which ones are optional? What are the best practices for a given task? What are the related tasks? Plus, is there one type of user who performs all administration tasks or are there different types of administrators using different administrative user interfaces and performing different sets of tasks?

Many people in the field of communication may have an idea of what is meant by an administrator in the context of software development. But the idea of what an admin does is general and not specific, I think. For example, people may think an administrator sets up user accounts for a system and applications. All users have user names and passwords, permission levels set for each application, database, server repository, community, user group, and so on, for each collection of available information and service and application that is available on systems to control who can see and do what.  So, you might want to ask some questions.

For example, does a database administrator install the database component of an application for which a server administrator configures a system? What required components such as an application server and repository must be set up? What user groups must be defined and specified with the correct authorizations for users to ensure required security protocols?

Do the same or different administrators install applications on server machines? Who does the configuration required on server applications? Who creates integrations between applications that require much configuration for servers to connect and communicate?

In what context does a user who needs to perform administration tasks such as creating a new state transition model for a system or add new attributes to a record type or other form of data in some kind of repository? Or, what administrator role works with developers to create a new product add-on or custom policy to govern the state transitions and integrate it into a system?

Some software products specify a project administrator role for the people who define and possibly manage the projects. But these users are not typically server or database administrators and will rely on these types of administrators to have the software available before they can create and configure a project. Since a system may be used for thousands or tens of thousands of projects, there may be a large number of project administrators.

These are just some of the examples of the complexity of software application administration.

So, rather than thinking in terms of an audience of administrators, you need to consider all the administration utilities and contexts, the tasks that can or must be completed, understand if they can all be completed with the same level of permissions or require different permissions, and help to articulate which administrator type does what tasks.

What is an end-user?

And end-user traditionally represents a user of some kind of client application – this could be a web client, a remote client such as an Eclipse client application or other application that resides on a computer that connects to an application server that governs the access and business logic for the tasks or operations that an end-user performs. Different end-users have different levels of access based on authorization (which is set up by server administrators). But in reality, no one is called or considers themselves an end-user. These people have actual roles such as data entry, data analysis, credit verification, loan processing, inventory control, purchasing, and operations management.

Identifying the user roles and contexts for a client application depends on industry specifics and the actual implementation of an application. Whereas generic user assistance can be provided that describes “out of the box” product functionality for client applications, the reality of the usage model is that the collection of administrators (and possibly partners and third-party vendors as well) customize the functionality for industries and companies so the actual end-user tasks are less generalized and more specific to doing actual tasks that model a job role, not the software product functionality. For example, a task can be documented generically but customized information will need to be provided for a customized application that provides industry-specific contexts to the task for a specific role or job function.

Is this reality different than it ever was for documenting software? No. Is it handled differently nowadays? Yes, by leveraging the additional options for designing communication more effectively. There is now a wider prevalence of examples and articles that are publicly available. For example, if search IBM developerWorks ( you can quickly find examples of content for role-based tasks for different types of administrators and end-user applications. Searching on “project administrator,” repository administrator,” “server administrator” and filtering within “Rational” quickly provides a context for which Rational software products these roles apply.

More context…

Administrators setting up contexts for user to do their tasks may be working to design and deploy a software solution that integrates different tools and technologies. For example, to better enable collaboration across an enterprise, how do system architects design systems that incorporate requirements and feedback from many different types of colleagues, such as managers, testers, customer account and support representatives, development, usability, and documentation teams?

Less abstract and more industry-specific examples abound. For example, what procedures and policies must a loan officer complete before a loan can be approved? What policies and tests must pass before a missile or satellite guidance system is ready to be deployed?

What are the administration tasks required to make these kinds of use cases available for these specific types of users?

Some of the challenges of designing a system, or a system of systems, are described in scenarios known as architecture management (AM), enterprise architecture management (EAM), and collaborative architecture management (CAM). The solutions for these kinds of scenarios might include software that integrates an architecture modeling tool, requirements management, change management, test management, some kind of content management system, and a unified reporting mechanism for all these capabilities.

There are several other current terms that represent collaboration and portions of managing work for developing software, such as distributed development, globally distributed development (GDD), lifecycle management, collaborative lifecycle management (CLM), application lifecycle management (ALM), and so on.

Given these types of contexts, the audience for user assistance is the collection of administrators who must install and configure a system for the users of the system. Since there are most likely multiple products to install and integrate, these users will be looking for information on integrating one product and another. Since they will likely have corporate-specific requirements, they will also likely need to highly customize products with “out of the box” offerings and may need to integrate specific proprietary services or applications for which user assistance is provided. The most common path for this kind of integrating and extending product functionality is through programmatic access to and from applications using APIs. The publicly supported APIs for products are typically documented though the same administrator looking at creating the enterprise solution will likely not be doing the API-level programming. That work will need to be requested, tracked, and managed, however, before a full system deployment can be made available.

As a short comment on content and content types and what’s best for which audiences, there is much literature on the subject. For the roles described in this article, there is an abundance of web content (such as on developerWorks and There is plenty of multimedia (such as the movies available here: as well as product information centers ( For in-depth use case scenarios that may integrate multiple products, there are IBM Redbooks ( Filtering for the best subset of information continues to be an ongoing challenge.

Tagged on: