Technical Writing Best Practices
Documentation is critical to creating a safe security posture. Because so much of compliance is documentation, creating accurate technical documentation can empower a security team and play an integral role in security. A good Security Engineer should have a broad understanding of the industry and the documentation that supports it. Technical Writers can also assist by taking on the writing and archiving responsibilities. This is a quick guide that addresses some of the fundamentals for maintaining great cyber security documentation.
Understanding Cybersecurity Frameworks
When building cybersecurity documentation, having a broad understanding of cybersecurity frameworks is important. A good interpretation of NIST 800 Series and SOC2 Framework can be a guide when writing policies and procedures. Both of these frameworks provide the foundation for cybersecurity documentation best practices. While much of this information is written in broad strokes, it is up to the Technical Writer and cyber team to gather information and generate documentation.
If your organization is looking to build a cybersecurity framework from scratch, having a team of Security Engineers and Technical Writers available can help alleviate the stress of writing and styling. Each framework should have three elements (Core, Tier, and Profile). Building a framework profile is a way for organizations to align their requirements and objectives, risk appetite, and internal resources against the outcome of the Framework core.
There are many out-of-the-box resources for styling and datasheets. Resources like ITIL and COBIT can provide outlines that teams can use as reference points. From there, it is up to the cyber team to align each element to the framework’s components. A technical Writer should be present for all strategy meetings so that they have enough information to start writing. A solid framework should consist of 5 Pillars (Strategy, Design, Transition, Operation, and Improvement).
Research and Information Gathering
If you have hired a Technical Writer, chances are it was because of his or her writing ability. However, a large portion of a Technical Writer’s job is information gathering and research. Writers need to be able to dive into complicated topics, extract the right information from security engineers, and reveal that content in digestible, easy-to-understand documentation.
Good Technical Writers can mitigate the time required to gather information from Subject Matter Experts by asking the right questions. Having the foresight to define clear goals and objectives, a Technical Writer should be able to see past short-term milestones, building out the pieces of the overall document. Organization and appreciation of details are important aspects of meeting deadlines and staying on task.
Navigating Complex Systems
Writing cybersecurity documentation includes access and understanding of complex systems. Depending on the size and scale of security operations, it is not uncommon for your team to have access to all levels of the organization, from security analysts to program managers to C-Level Stakeholders.
Good security documentation is built from the bottom up and the top down. It’s important to give Technical Writers the support they need to interview all levels of the organization. This ensures that work gets done correctly the first go around, on time, and within budget.
Because a Technical Writer is a critical IT support function, each business unit should be aware of the goals and objectives and have access to the team of technical writers.
Here is a brief list:
- Service/Help Desk.
- Incident Management.
- Event Management.
- Asset Management.
- Application Management.
- Change Management.
- Knowledge Management.
- Improvement & Process Management.
Security Logging and Monitoring
A part of the maintenance of infrastructure is event logging and monitoring. Because each activity within an environment is a security event, these instances must be documented. Electronic audit files, unauthorized events, and digital threats should all be carefully logged and moved into a database for additional investigation and action.
In many instances, this data is unstructured and disorganized. It is up to the cybersecurity team to present this data so that it can be viewed and analyzed. In doing so, teams can protect against a security breach, analyze malicious external threats, and guard against the misuse of information. Audit logs are available for review if a breach should occur to facilitate a reconstruction of the event.
While many security systems have embedded software used to monitor and log the data surrounding events, it usually falls on the security team to digest the information, analyze the risks, and prepare the documentation for review. Many teams have trouble allocating continuous resources to event monitoring and logging because they are not competent in writing. Having a Technical Writer dedicated to documenting these events is often the best way to prepare for a security audit or reconstruction.
Policy, Training, and User Guides
Complex systems have many moving parts. Sometimes, you can rely on vendor documentation to help cyber teams understand how to use, install, and train on these systems. Often, teams need a more customized approach to learning about complex systems.
Having Policy Development and Management User-Guides is a way to develop and maintain clear policies for keeping complex systems safe. Many policies are tailored for real-world situations and must be customized to the specific organization and updated regularly. It’s a good idea to develop a cyber plan that reflects good design and governance practices.
Here is a list of cyber action items:
- Privacy and Data
- Network Security
- Web Application Security
- Mobile Devices
- Facility Security
- Incident Response and Reporting
- Policy Development
- Authentication and Authorization.
Great cybersecurity technical documentation does not stop and start at writing. A good writer needs to conduct reviews of proposed publications for style, design, and layout. Effectively researching and analyzing abundant technical questions, issues or events involves helping support mission critical infrastructure.
Gathering information from subject matter experts, and program personnel is important when writing to policy and regulations in supporting the developing, writing, formatting, and editing of technical reports, manuals, procedures, briefs, and other forms of documentation.
In Closing
Good technical documentation involves tracking, logging, and consulting with technical staff to determine the formatting and content needed to review and write technical reports and policies. User manuals, training materials, installation guides, and system specifications are all needed to support the organization. Data calls, response consolidation, providing recommendations, maintaining spreadsheets, creating presentations, facilitating meets, and recording meeting minutes are all part of the job description.
Having a working knowledge of federal cybersecurity protection standards and baselines like NIST 800 series is important. Evaluating compliance with the organization’s security policies and being able to make recommendations for areas of improvement goes a long way for employers and teams.
Updating cybersecurity policy documents, system security plans, baseline and threat models for deployment, and risk acceptance decisions are also good topics.