Mar 262016

[Ed. Note: We are pleased to offer the first of a two-part article on techcomm in service organizations.]

Part 1—Documentation for Companies with No Products

Technical communicators find themselves in a rapidly changing marketplace. While “technical writer” is still a common job title, many communicators are now tasked with creating instructional videos, information graphics, and Web site content as well as traditional documentation such as manuals and online help. But while our deliverables now include new kinds of content, our goal remains the same—providing users with the information they need to use the product.

noun_161513_ccBut what about companies that don’t sell “products” as we commonly understand them? An increasing number of technology start-ups, as well as divisions of established companies, do not sell hardware or software artifacts. Instead, they provide services. Customers hire these companies to perform particular tasks, such as billing, data analytics, or cloud storage, rather than handling these tasks in-house. Customers might never install any software or hardware at their own facilities, and pay for the service on a per-use basis. What is the role of the technical communicator in service organizations, where there is no product to document?

This two-part series explores the communication needs of technology service companies, and how technical communicators play an essential role in enabling these companies to function. It also explores how writing for service company employees differs from writing for external clients, and what assumptions and habits communicators often bring from past roles in product organizations that must be tweaked for the service industry.

Platform Versus Product

Service companies perform work in every sector of the global economy. Banking, insurance, tourism, retail, medical and law enforcement are only a few examples of industries that make extensive use of service companies. Services provide a cost-effective alternative to hiring staff and installing complicated systems within the customer’s own organization. Examples of services include cloud storage and file sharing, content management platforms, call center staffing and automation, energy usage monitoring, language translation, and media streaming.


Many services are provided by multiple companies working in tandem. For example, a retail store might offer a customer service telephone number. When a customer calls the number and asks for technical assistance, the caller’s statement might first be parsed by a voice-recognition service, and then passed to a call center provider to complete portions of the call that require a human agent. Finally, the claim against the retail product’s warranty might be processed and recorded by another company. All of this occurs transparently to the caller, who is unaware that the call has been routed through several different companies in the span of a few seconds.

In the scenario above, each organization benefits by outsourcing work to another company. The retail company does not have to buy an expensive voice-recognition program or develop a phone tree application to route callers to the correct department, because the voice-recognition company provides these services. While the cost of developing and maintaining a voice-recognition platform is substantial, the service provider works with numerous clients, so the development costs are spread out between multiple revenue sources. The voice-recognition provider, in turn, outsources portions of the call that cannot be reliably handled by its service to a call-center provider—who then uses a data-management company to handle warranty claims.

The Information Needs of Service Providers

In a service scenario, the customer does not take possession of products after using the service. A task is simply performed and billed. It might seem that technical documentation has little role to play in such an intangible exchange between clients and service providers. But when we look inside the service provider’s operation, we see that documentation plays a key role in operating and maintaining the service platform. The following sections describe some of the essential contributions that technical communicators can make in service organizations.


noun_130909Service companies are fast-paced organizations with frequent turnover. Unlike an installed product installed at an off-site customer, a technical service cannot tolerate bugs or wait until the next release to address performance issues. Every second that a service is down, the company loses money and the trust of its customers. Reported issues need to be fixed immediately, and service companies do not have the luxury of bringing new employees up to speed slowly. New employees must master their areas of responsibility and become contributors immediately.

Technical communicators play a key role in training new staff at service companies. While engineers, network administrators and other team members all help new colleagues learn their duties, technical communicators are one of the few staff members who can describe the service in its totality. A network administrator, for example, might understand the detailed configuration of the service’s routers and data centers, but be largely unaware of the middleware programs that actually enable the service to run on the network hardware. A sales associate might be able to describe the customer experience provided by the service, but be unable to list the technical requirements for connecting to the service. If new employees are not given a start-to-finish introduction to all the components of the service, they risk being isolated into the silos of their respective teams.

When a team masters its own responsibilities but remains in the dark about other teams’ projects, the service can quickly crumble. For example, application developers might make changes to the metadata used to label transactions flowing through the software servers—unaware that the database administrators are migrating the reporting databases to a new release version that is untested with the application developers’ changes. This could make the reporting platform erroneous or inaccessible for hours or days, and ultimately force one of the teams to roll back their changes, resulting in lost productivity.

Knowledge Management


A service company produces a staggering amount of information in the course of its operation. From the early request-for-proposal and statement-of-work documents that initiate a new client project, to the network maps and server rack diagrams used by network administrators in the day-to-day maintenance of the service’s data centers, documentation describes, shapes, and captures the actions taken by the company’s teams. A growing company can generate thousands of documents every year. While cloud-based tools such as Google Apps or Microsoft SharePoint allow employees to access these documents from any device, the task of organizing and tracking these artifacts remains as difficult as ever. Arguably, features such as the granular “sharing” of documents in Google Drive have made it harder to track and organize the data produced during a typical work week.

Few employees have a knack for organizing information. The promise of knowledge-sharing platforms is seldom realized unless a talented employee is tasked with designing, publishing, and maintaining the platform’s contents. Technical teams often dump documents haphazardly into a wiki and rely on “What’s New” feeds to stay on top of recent work. Soon the wiki becomes useless to new employees or other employees who need to check their own work against the team’s.

Technical communicators bring unique skills and experience to a service organization struggling with its deluge of documents. Other employees seldom realize that the documents they generate can be of value to other teams. They aren’t accustomed to thinking of their colleagues as readers and as discrete audiences for the company’s information.

For example, the company’s business analysts and service design team might write functional specifications that outline how the service integrates with the client’s billing system using a third-party API. This information can be buried inside a 20-page Word document attached to a wiki page. The company’s customer support division probably isn’t aware that these documents exist, or where to find them. When the client reports a service disruption, the support team might waste hours investigating the issue before concluding that the disruption is caused by the client’s own system because they can’t locate an error in the platform. The technical communicator can make the support team more effective by connecting them with all the information on each client’s configuration.

Common Terminology

Service companies are made up of teams that each work with some part of the company’s technical infrastructure to keep the service running. But without a technical communicator to document and describe the service’s components, each team is apt to casually invent their own terms for the service’s parts. For example, the network administration team might know that a key application that routes data through the platform is an Apache Tomcat server. In conversation, they may call the application “Tomcat.” Meanwhile, the developers might have given the server’s Web application a particular name, such as “the media server.” When teams don’t use the same terms, miscommunications are inevitable—and in a service company, miscommunication can mean hours of downtime and lost revenue.

Inter-Company Communication

noun_206893_ccService company teams often work in silos, devoted to particular tasks related to running and maintaining the service platform. Just as lack of awareness and miscommunication between teams can bring down the service, another threat is uncoordinated actions by different teams. Technical communicators should position their work not just as reference documents that are consulted when problems arise, but as publications that actively alert each team of the technical progress being made by their colleges. Today’s wiki and file-sharing platforms notify subscribers when documents are changed and shared, and technical communicators can add descriptions of the document’s changes to these announcements. This makes the technical communicator a point of contact between the various teams—and leaves team members no excuse for not reading the company’s documents.

Laying Foundations for Future Development

Curating the company’s content and enabling inter-team discussions allow teams to brainstorm and collaborate towards new designs and improved features. When everyone is literally on the same page, explanations can be brief and substantial discussions can begin immediately.

When Service Becomes Product

The rapid pace of today’s technology industry and the frequent changes in ownership and management of organizations means that a company’s development and business strategies are always tentative and subject to about-face reversals. This means that technology that starts as a service sold to customers on a per-use basis might be transformed into a product suite installed on-premise at customer sites—and developers, designers and project managers might be given tight schedules to make this transformation happen.

noun_84987_ccFor example, a company might start as a music-streaming service. If the company is successful, however, it becomes ripe for acquisition. It could become part of a larger company that sells software and hardware, and its music streaming platform might be re-purposed to handle video and other types of content sold by its new owner, with tablet apps and other tools designed as the service’s new user interface.

The documentation provided by the technical communicator is the starting point for future development and design work that turns the original service into a product worthy of sale. Without the list of tasks and procedures compiled in the documentation, the product teams are doomed to flail as they try to define the new product’s requirements and delivery schedule.

Next time I’ll talk about the challenges technical communicators face at service companies.

About the Author

Jason Dickey is Principal Information Architect at Interactions Corporation in Franklin, Massachusetts. He has worked as a technical writer, user experience designer and knowledge manager for telecommunication, cloud storage, artificial intelligence and financial services companies. He is currently researching best practices for designing voice and text interactions between human users and artificial intelligence agents using natural language processing, voice biometrics and automated speech recognition in service environments.