Notes from the Other Side: It’s Different Working In-House!

Home/Publications/Best Practices Newsletter/2009 – Best Practices Newsletter/Notes from the Other Side: It’s Different Working In-House!



June 2009

Notes from the Other Side: It’s Different Working In-House!

CIDMIconNewsletter Lea Novak, Princeton University

After many years of working with software development companies, I started working for the Office of Information Technology at a prominent university. Having worked in the field for nearly 20 years before starting at the University, I thought I knew what to expect. I was wrong. There are some significant differences between working on documentation to be used in-house and documentation sold to outside users as part of an application.

Most of the differences result from the size and focus of the organization, the identity and relationship with the target audience, and the composition of the development project team. Some of these differences may not apply if your company is a large, multinational one with offices around the world, but if your company is small, as the University is, read on. The differences you expect can express themselves in unexpected ways.

The Size and Focus of the Organization

In software development companies, the primary focus of the entire organization is the creation, sale, and delivery of software and supporting materials. Most of the resources of the company are involved in this process, and the development and documentation staffs tend to be large. In addition, because the software is sold to users outside the company, user documentation is very important. It can be used as a sales and marketing tool, as well as providing support for the users. It is part of the package, tested, and delivered with the software. If the documentation isn’t ready, the product can’t be delivered.

At the University, the primary focus is education, supported by the applications that keep the institution running. This seemingly small difference has the following practical effects:

  • Documentation is not a line (production) department, but a staff (support) department. This is an important distinction, because it means we are not core to the University’s function. We are more at risk from budget cuts, staff reductions, and general cost-saving measures. Implementation schedules are based on the academic calendar, and generally don’t take documentation resource availability into account.
  • While the Office of Information Technology is not small, the group that creates and implements applications is, and there is only one writer. While that means that I have more control (over tool selection, style, and consistency), and I get to dabble my fingers in every pie, it also means that there are no extra resources to fall back on in a crunch and no sounding board for professional brainstorming or analysis.
  • Moreover, the software isn’t being sold to our users; there is no package, no sales or marketing, and user support can be handled in other ways. Since the University is an educational institution, it comes as no surprise that training is one of the primary methods of support, followed closely by the help desk. If documentation isn’t ready when the application is ready to go live, it has been known to go without.

This leads me to the next big difference—the target audience.

The Identity of and Relationship With the Users

When you work for a software development company, your target audience is usually the paying customer. The users are often not well known and are not readily accessible.

When you are working in-house, your target audience consists of fellow staff members, which has the following implications:

  • You may know the users personally and may be able to chat with them casually about what they need, what they like, and what they use.
  • If you don’t know the users personally, it is at least easier to set up focus meetings with them—they’re on site, and they work for the same company, which has a vested interest in making sure they get what they need to do their jobs.
  • In the case of a small institution, such as the University, there is no need for translation and globalization of documentation. All the users are local, and even those who do speak a foreign language would not expect multilingual documentation.
  • Another result of being a small institution is that we don’t need large numbers of printed documents. Print runs average about 100 copies, with occasional larger runs if an application targets students or all staff members.
  • On the down side, the users are a captive audience—they can’t go elsewhere and buy a competing product. In that sense, they have very little clout.

Composition of Development Project Team

Last, but by no means least, is the composition of the development team. In my previous jobs in software development companies, the development project team was likely to include software engineers, a representative from marketing and/or sales, one or more technical communicators, and possibly someone from training or consulting. When I first started at the University, the development team included the software engineers and possibly a technical writer. But that changed with the new millennium and the implementation of the Partnership 2000 initiative, when the University decided to change the way we manage information technology projects.

Figure 1 illustrates the relationships between the technical staff and the business office staff.

Novak_Figure 1

The new project management methodology at the University includes a governance model that has the project manager coming out of the sponsoring business unit, for example, the Registrar’s Office, the Treasurer’s Office, or Human Resources. Under the project manager is the technical project manager and possibly a business project manager. The software engineers report to the technical project manager. But the business project manager is responsible for all the users from various business offices who are on the project team. These users are generally more “super users” than normal end users and are responsible for requirements analysis, specifications, and both QA and user acceptance testing. They are also responsible for providing information to the technical writers and reviewing the resulting documents.

You can see in this model that while the writers are part of the technical team, there are more lines of communication with the business users than there are with the technical project team members. You can also see how closely the users are involved with the developers. This project governance model is only possible for projects that are completely in-house.

The primary benefit of this model is that you can work very closely with the users. These users are not always your target audience, but they know your target audience and their business functions. They work with the developers to determine requirements, write specifications, and test the application. So they know the application, its purpose, its intended use, and the people who will use it. They are a treasure trove of information, and they’re on the same project team with us!

We consult with these “super users” when we are determining what pieces of documentation will be needed, what should be included in each piece, and how each piece should be delivered. We meet with them again to review the outline(s) and call them for help in setting up scenario data. They answer our questions while we are working on the first draft, and then they review the documentation through multiple review cycles.

The trainers and support specialists are also readily accessible, providing us with more insight into the users and feedback about where they have problems.

Unforeseen Complications

Of course, there are some unforeseen complications of this project model. Two areas were particularly surprising: building bridges between users and developers and determining just how much user involvement is reasonable.

Building Bridges

With users on the project team, you might think that bridging the gap between developers and users would be a less significant part of the technical communicator’s job. I found, however, that bridge building is still important, just in different ways:

  • Sometimes the users are your bridge to the developers.
    1. When your primary source of information is the users, you can find yourself estranged from the technical team members. I found that it worked best to report bugs and oddities to the business users, who could then send bug reports and improvement requests to the developers.
    2. After implementation, the users are the ones who request and then test changes to the system. We often don’t even hear about changes until they show up during a training session. We are still working on finding a solution to this one.
  • Sometimes you are the bridge from the users to the developers but in the background.
    1. I could suggest improvements to the users, but I had to let them do the asking, because the developers tended to discount my input in favor of direct input from the users. In other words, “if the users didn’t ask for it, they must not need it,” and who was I to say they did?
  • Sometimes you are the bridge from the super users to the end users, but sometimes they know the end users better than you do.
    1. The super users can become too close to the system and don’t always realize that end users may find it confusing. I often had to point out areas that I found confusing and speak for the end user.
    2. However, sometimes they do know the end users better than you do. This can require a real readjustment to your perspective!

How Much User Involvement Is Reasonable?

When your users are your primary source of information, it is a very short step to asking them to write the documentation, especially when your technical communications group is very small. We experimented with various ways of involving the “super users” in the documentation effort.

  • We began by asking them only to review the documentation. This tactic worked very well, as long as we were adequately staffed.
  • When we ran into staffing issues, we asked project team members to write drafts of chapters. We worked out the outline together and then distributed two or three chapters each to three project team members. Then we edited the material (extensively), captured screen shots, and added callouts. We also created the index and table of contents. Using this method, we were able to complete the documentation on time, but we all put in considerable overtime to meet the deadline.
  • As our staffing levels continued to drop, we asked the “super users” to create their own central office documentation while we provided the documentation for distributed users. We gave them a tool that captures screen shots and actions with appropriate text as you perform the procedure. Unfortunately, this seems to have pushed user involvement past the reasonable limit. Most of the central office documentation is still not completed six months after the upgrade.

Our conclusion is that users don’t have the time to write documentation in addition to their other tasks. Dedicated writers, whose priority is documentation, are more likely to complete the job on schedule. However, since staffing remains an issue, we are still looking for ways to enlist the users in the documentation effort. Our next experiment may be to ask the users to update the documentation when the system changes, since they are more likely to know when updates are needed. However, this idea is still under review.

In Closing

Working in-house still involves most of the usual challenges in the documentation world. However, in many ways, it is very different from working in a corporate environment.

The summary of differences are in tables are below.

Novak_Table 1Novak_Table 2

The closer involvement with the target audience is a key advantage that can be leveraged to create better, more usable documentation. Wherever you are, the job is still about communication and, to do that well, you have to know your audience. It’s just a lot easier to know your audience when you’re working in-house. CIDMIconNewsletter

About the Author



Lea Novak
Princeton University

Lea Novak began her career as a Cobol programmer, but after 4 years returned to her roots, and became a technical writer. After working for two software development companies and two consulting companies over the course of 12 years, Lea began working for Princeton University. As part of the Office of Information Technology, she plans and creates user documentation for business applications implemented at the University. While working at Princeton, Lea was involved in researching and recommending development and project management methodologies, as well as leading the documentation group through several software implementation and upgrade projects. Lea also researched, planned, and implemented a switch from Word and RoboHelp to FrameMaker and WebWorks ePublisher, and designed the templates for the new systems.