Jul 232017

Icon showing a checklist under a magnifying glass (credit: Kevin Augustine LO from The Noun Project) Information Security is one of the hottest jobs in technology today. This is for good reason—stories of stolen identities, medical records, and political secrets dominate our headlines and undermine trust in schools, stores, corporations, and even the governments of world powers. Technical communicators can play an important role in assuring that doesn’t happen.

Information Security professionals are often the most successful when you don’t hear of them. A system that is never hacked and keeps its data safe from ransomware doesn’t make the headlines.

But when information security fails, entire companies, brands, and the careers that depend on them can collapse. Leaked trade secrets, stolen data, or services crashed by hackers can lay waste to years of strategic planning and carefully cultivated reputations—to say nothing of the lost revenue and sales that occur as a result.

Faced with such high stakes, governments and businesses that use services from technology vendors are no longer content to trust the assurances of their vendors that all client data is safe. To protect themselves, industries and governments insist that their vendors meet rigorous standards and prove that they comply. This is often accomplished by contracting auditors to review the vendor’s systems, policies, and procedures to certify that they meet the requirements set forth in industry or federally mandated security protocols. The auditors often work on-site at the vendor company, performing tests on the company’s systems and collecting information on the company’s processes. Security audits are often part of a broader IT audit that assess the company’s systems to ensure their reliability and capacity, as well as their safety from hackers. This is where we come in.

Writing for Auditors

Depending on your company’s industry and clientele, audits can occur through the year. Companies that serve clients in multiple industries (for example, a cloud storage vendor that retains records for medical, retail, and utility companies) can face numerous audits, sometimes occurring simultaneously. For example, a single service company might have clients that require certification for the following standards:

Security audits are usually handled by the company’s Information Security officer working in cooperation with the auditors. Audits can include tests of the company’s system to ensure that it can repel hackers (penetration testing) as well as reviews of the company’s policies and record-keeping to ensure that the company keeps an adequate paper trail, takes appropriate steps to vet new software releases before they are deployed to production environments, and reports incidents in a timely and complete manner.

Audits are often a stressful time for management—especially for startup companies that previously operated with loose and ill-defined policies, but now aim to expand into markets that  demand legal compliance with tight standards. Auditors can make sudden requests for information and documents that might not exist, at least in formats suitable for legal certification, and timelines can be tight, closer to the looming deadlines of a newspaper than the weeks-long project plans of most development work. Technical communicators may also find that these documentation demands subject them to a new level of scrutiny—rather than pleading with subject matter experts to review a manual, technical communicators might find their work demanded by C-level executives who parse every line.

The following sections discuss the types of documents that technical communicators can be called upon to provide during an audit and how technical communicators can use the stressful audit periods to enhance their perceived value within their organizations.

Policies and Procedures

Most security standards require companies to have explicit policies and procedures that describe how information is kept secure. Accreditation agencies often provide templates for these documents, which can be adhered to with varying degrees of imitation, depending on the standard’s requirements. For example, FedRamp requires documentation on the following aspects of a company’s system and business processes:

  • Configuration Management Policy and Plan
  • Baseline Configuration
  • Configuration Change Control
  • Security Impact Analysis
  • Configuration Settings
  • Information System Component Inventory

When a company first tries to gain accreditation for a standard or demonstrate its compliance for a prospective client, it often lacks the required documents. A technical communicator can be tasked to create these documents with little advance notice and little time to prepare. In startup companies, there may be no real policy or procedure for performing these tasks—each previous case may have been treated as a one-off, and performed according to the best judgment of the network administrators and developers at the time.

In the absence of an established canon of policies and procedures, the technical communicator can make a lasting contribution to the stability and future growth of the company by creating template procedures based on past projects (for example, of new deployments of software patches in the company’s network). Often, the mere existence of a policy document—even a hastily written draft with many key details missing—is enough to spark discussion and decisions by management staff that set the direction for future work. This allows the technical communicator an opportunity to not only meet the immediate needs of the audit or certification, but to have a tangible impact on the future development of the company’s signature products and services. The importance of these contributions underscores the fact that documentation is not only a reactive task that occurs after development is done, it also brings order and coherence to the entire development effort and lays the groundwork for future growth.

System Architecture Diagrams and Inventory

A simple architecture diagram showing, from left to right: blog readers; a page server and a comment server, with which readers interact; an app server, which pushes content to the page server and receivers connect from the comment server; and authors, who push content to the app server

A simple system diagram restricts itself to the components under review

Many audits are concerned with technical details of the system. For example, PCI audits are concerned with the firewalls used to protect sensitive data and the safeguards that ensure data is archived and retained in secure facilities. When a company’s managers gather information for auditors, they often ponder how much information they need to provide to meet the audit standards. Revealing too many details beyond the requirements of the audit can compromise the intellectual property of the company. But providing minimalist documentation aimed at satisfying the demands of the audit, without overwhelming the auditors with excess details, also helps the auditors complete their assessments quickly and easily. A system diagram that restricts itself to the components under review by the auditors is more easily digested than a diagram that sprawls over multiple PDF pages and contains overlapping lines between each server labeled with ports, protocols, and other information outside the scope of the audit.

Many network management tools, like NetBrain or VisualOps, generate complex diagrams of the network architecture as well as inventory spreadsheets listing the resources deployed in the network. But these are usually full of excessive details and can be difficult to decipher. It is usually the technical communicator who can translate the complex schematics exported from the tools into legible diagrams and documentation that satisfy the auditor’s demands.

Tools and Vendors

Security standards spell out activities and tasks the company must perform to merit certification. To pass an audit, the company must demonstrate how these activities and tasks are accomplished. For example, the security standard might insist that the company track every user-performed action that changes the configuration parameters of the production server environment. The company might have a number of audit tools available, such as screens in each of the system’s GUI tools that list prior actions performed by the tools, and system logs that can be read using Splunk or another query tool.

More than likely, the technical communicator has documented all the GUI tools and techniques for the system’s users long before the auditor requests the information. The instructional documentation can then be repurposed to satisfy the auditor’s needs.

Similarly, the auditors often request technical specifications for the software produced by the company, and the hardware and server platforms it utilizes. This information should also be readily available from work the technical communicator did previously.

Making Documentation Departments Ready for Auditors

Often, when management realizes they must comply with an auditor’s request, technical communicators are tasked with providing audit documents within a matter of hours or days. This information might be available in various documents—but it has to be put together in formats acceptable by the auditing agencies. You can’t simply submit a set of user guides and release notes written for other audiences, full of extra details for other audiences, to satisfy an auditor’s requirements. This makes writing assignments sparked by auditor requests into stressful, rushed deliverables that can force the writer to work well into the night—while information security personnel and executives wait anxiously for the final documents.

To make audits as stress-free as possible, technical communicators should familiarize themselves with the audit standards that apply to their company, and develop rapport with the information security and IT teams. Technical communicators should also regard auditors as a regular audience of their documentation, and plan their documentation strategies and architecture so content can easily be reused for upcoming audits. The following suggestions can help ensure that audits run smoothly and technical communicators have the lead-time to prepare for them.

  1. Technical communicators should confer with the information security and IT teams about upcoming audits and the standards used to assess the company. An audit calendar and inclusion of technical communicators in the company’s work tracking system, such as JIRA, can ensure that technical communicators have the advance notice needed to have information ready to hand over to the auditors without delay. 
  2. Technical communicators should learn the security standards used to assess their employers and the documentation requirements of each standard. Fortunately, the general details of each standard are readily available online, with Web sites and knowledge bases available from most standards agencies. Training sessions, such as “lunch-n-learns” and professional development seminars, provide good opportunities to introduce colleagues to the requirements of the company’s audit responsibilities and spark team discussions about preparing content to meet auditor inquiries.  
  3. Much of the information required by IT audits can be exported to diagrams and spreadsheets from network management tools like SolarWinds and NetBrain. The documents produced by these tools often need refinement in tools like Visio or Excel before they are shared with the auditors. Technical communicators can save time by learning how to use these tools to export documents and setting the export parameters to capture only the relevant details. 
  4. Many audit documents are assembled from earlier documents. Technical communicators using single-sourcing tools, such as MadCap Flare or AuthorIT, should take advantage of these tools’ abilities (such as conditional text and multiple outputs) to generate audit documents from existing content. For example, technical communicators who use DITA can assemble the general policy and procedure documents from concept and task topics, and use reference topics in combination with the diagrams and inventory spreadsheets produced by the network monitoring tools to satisfy inquiries about the system’s components and configuration settings.

Audits as Opportunities to Show Value

IT and security audits provide excellent opportunities for technical communicators to showcase the value of their work to high-level executives and decision-makers in their companies. Audits prove that documentation and technical communication skills are vital for companies to operate and earn their clients’ trust. Tackling audits can be stressful and put technical communicators under the anxious gaze of upper management, but meeting these challenges can raise the writer’s profile within the organization and give the writer the chance to make lasting contributions to the organization’s processes and day-to-day operation.

About the Author

Headshot of Jason DickeyLinkedIn

Jason Dickey

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. Jason is Treasurer of the STC New England Chapter.