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.
back to top


Introducing the ACM SIGDOC@NCSU Student Chapter

In Spring 2010, the longstanding STC Student Chapter at North Carolina State University (NCSU) decided to make a change. After much debate and deliberation, the award-winning chapter decided to close in order to make room for a new organization—the ACM SIGDOC. Deciding to become the first graduate student chapter of the ACM SIGDOC, the former STC board members thought that the change would reflect an awareness of interdisciplinary collaboration in their field. While most of the new ACM SIGDOC@NCSU officers hailed from NCSU’s MS in Technical Communication program, they recognized that their work was no longer limited to manual writing and document design. Their degrees were expanding, a truth reflected in their diverse coursework. While still focusing on technical writing and project management, the students had also began studying web development, graphic design, video and audio development, social media, e-learning, Internet ethics, organizational communication, usability, and cognitive psychology.  These new academic endeavors helped the students and advisors to realize that the theory and practice of “design of communication” was changing. Thanks to innovative technologies and changes in the way we communicate, new and emerging disciplines were filtering into their field. Faculty and advisors noticed that employers and companies were beginning to understand the importance of effective communication in an era of instant communication, and they passed this news onto their students with novel special topics courses and challenging new projects. As a student chapter, the former STC officers wanted to send this message as well. Whether the workforce desired manual writers, web developers, instructional designers or information architects, the ACM SIGDOC@NCSU Chapter wanted to help prepare students for inevitable changes to the field.

As anyone who has tried to start a new chapter or organization is aware, the first few hurdles involved paperwork and red tape. The students worked with their forward-thinking faculty advisor, Sarah Egan Warren, to develop a chapter constitution and file for official recognition among NCSU’s student organizations. One of their first members and officers, Jen Riehle, developed a unique website integrating OrgSync, a social network for student organizations. They started with social events and networking opportunities, extending their outreach to the student, faculty, and alumni of the NCSU MS in Technical Communication program ( <>  < During their officer meetings, the students discussed how they would reach out to other disciplines at NCSU and other programs in North Carolina. The students recognized that, as the first graduate student chapter of the ACM SIGDOC, they needed to set the bar high.

A great success of the organization so far is their connection with the Pathfinder Program at IBM ( With its next-door neighbor location in Research Triangle Park (RTP), IBM is a perfect partner for ACM SIGDOC students who want to learn more about real-world employment opportunities available to them. The Pathfinder Program allows students to work with a mentor for about a year. It’s a flexible program that allows students and mentors to decide how they want to use their time, whether it be through monthly meetings, resumé review and interview practice, or job-shadowing opportunities. ACM SIGDOC@NCSU helped interested students to join and succeed in this program, offering testimonies from students who had benefited from Pathfinder in the past. By the end of the year, many students had successfully completed the Pathfinder Program, three students continued from the program into an IBM internship position, and one student, Pathfinder alumni and ACM SIGDOC@NCSU Board Member Neal Timpie, turned his internship into a full-time position with the IBM Lotus Team.

The chapter also worked with alumni who were willing to graciously donate their time and resources to the chapter. These alumni included Anna Thompson, a Marketing Communication Specialist for Research Triangle Institute (RTI); John Martin, an Information and News Technical Support Analyst for NCSU’s Office of Information Technology (OIT); and Christin Phelps, a doctoral student in NCSU’s Communication, Rhetoric, and Digital Media (CRDM) program and instructor for the undergraduate Designing Web Communication course. Thanks to these alumni and to student-professional outreach programs, ACM SIGDOC@NCSU is achieving its goal of connecting students to real-time information about careers and job marketability.

The new chapter has exciting plans for the future. Officers planning to return next year are discussing the possibility of an ACM SIGDOC@NCSU-inspired conference tentatively named “SIGDOC SpeedCon.” The student-led conference would give the chapter a chance to invite other disciplines and programs into the conversation while also giving students a chance to present their work and ideas. The Chapter’s Faculty Advisor, Sarah Egan Warren, continues to support and inspire the students as they think of new ways to share and discuss the design of communication. ACM SIGDOC Chair, Dr. Brad Mehlenbacher, has also been able to offer his support, attending chapter events and meetings, and excited about offering his advice and expertise to the new chapter.

With a summer to plan and a group of new students ready to lead, there’s no telling where this chapter will be by the end of year two!

back to top

European Chapter of SIGDOC

Carlos Costa is working on the EUROSIGDOC website with his students:

OSDOC 2011 ( will take place on July 11th in Lisboa, Portugal. This is a SIGDOC European Chapter event in Open Source and Design of Communication. The workshop main topics are: open source and technical writing, open source and creative commons, open source editing tools, open source and games, open source and HCI, ERP Open Source, open source and organizational systems. Everyone is welcome to participate.

CFP of  OSDOC 2011: This CFP is about to close,and we think we have more submissions than last year! 


back to top

ITmatters@IU Newsletter

One of our former conference sponsor, Indiana University School of Informatics and Computing, has just released their IU’s “ITmatters@IU” newsletter. It features the School of Informatics and Computing’s two Webby awards in the School/University category. Take a look!

For more information on the program, contact James P. Shea, Director of Planning and Communications (

back to top


Call for Papers from ICCATE 2011

2011 SSITE International Conference on Computers and Advanced Technology in Education will be held on November 3-4, 2011, Beijing, China.

ICCATE 2011 will be the most comprehensive Conference focused on the various aspects of advances in Computer Science and Education. Our Conference provides a chance for academic and industry professionals to discuss recent progress in the area of Computer Science and Education.

The goal of this Conference is to bring together the researchers from academia and industry as well as practitioners to share ideas, problems and solutions relating to the multifaceted aspects of Computer Science and Education.

Topics of interest include, but are not limited to: Computer Science, Database Technology, Artificial Intelligence, Computer Architecture, Software Engineering, Computer Graphics, Computer Application, Control Technology, Systems Engineering, Network Technology, Communication Technology, Web Applications, Computer Education, Computer Education for Graduates, Computer Education for Undergraduates, Distance Education for Computers, Life-long education, Computer Education for Special Group, Other Computer Education.

All accepted papers will be included in the Springer CCIS proceedings (EI and ISTP).


The submission system is open.

Paper format see:

Paper Submission Due: July 10-30, 2011

Contact Email:

Tel: + (86) 186 2787 2331

Tagged on: