Our Blog

Beneath the Hoodie: The Challenge of Security Documentation

July 6, 2017 - Marketing to Developers -
By: Patrick O'Fallon

Technical documentation is a critical pillar to the success of the modern product company, yet it commonly falls short of the level of quality required to assist users and engage the vendor’s customer community. While this shortfall seems relatively insignificant, a lack of quality documentation can, in many cases, directly relate to customer success and retention issues.

Security documentation in particular falls victim to this trap—not only because of the complexity of the documentation itself, but also because of the rapid pace of change that SecOps consistently undergoes. Given the immense need for quality documentation within SecOps, coupled with the challenge of creating quality and up-to-date content, how can SecOps vendors go about tackling this challenge?

As the world reflects on the latest WannaCry ransomware attack, it is obvious that many organizations were hit because of an operational inefficiency due to lack of customer education and trust. To put it simply, software that should have been up-to-date wasn’t. Windows patches should have been installed prior to the WannaCry release, but either the users did not trust the patches, or they were not informed of the severity of the issue. The result is an immense vulnerability landscape due to ITOps patch management configuration issues. If simple and understandable documentation existed behind the notifications and update schedules, SecOps and ITOps professionals could have cross-referenced their patch management systems with vendor documentation, and the world could have closed the door to WannaCry much faster.

This highlights a very important point. Documentation is not simply a user education tool—It can also keep users up-to-date with the latest changes and functionality, and ensure they leverage best practices in their implementation. WannaCry is a good example of where high-quality documentation and user education can immensely help solve some major problems facing the SecOps and ITOps industries. Relaying critical information, changes/updates, and best practices to the end user is quickly becoming a necessity.

The Challenge

The security landscape is fast-paced and rapidly adapting to new attacks, malware variants, ransomware, and advanced, persistent threats. As a result, security vendors have their eyes fixed on ensuring their technology is addressing this ever-pressing wave of new threats. Yet, while their attention is fixed on keeping their products current, support and documentation take a back seat.

Nobody disagrees that threat management and product release should be the primary focus of the security vendor, but if users are not leveraging that technology, users may actually get hit by a security incident leading to churn in the vendor’s sales process. For example, a user may have a firewall, but not have advanced deep packet inspection or advanced threat protection enabled. If they get hit by an advanced threat and are told by support that they did not leverage the product successfully, this is a recipe for disaster for the vendor’s customer success.

High-quality Documentation

What makes for high-quality security documentation? Lets briefly discuss some key tenants.

    • Relevance: The quickest way to let customers down is to not have up-to-date documentation relevant to current product operation. This is more common than you think, and is potent enough to ruin the customer experience, and cost the vendor a support call.
    • Simplicity: High quality does not mean technically complex. The objective is to communicate highly technical information to the end user in the most simple and understandable format.
    • No Walls of Text: Images are priceless in security documentation—but beware of the trap of creating complex diagrams and flowcharts to relay your information. Ensure these images remain simple representations of your objective. 
    • Change Management: If the product has adapted or changed, these changes need to be reflected within the documentation.
    • Best Practices: Deploy best practices as a default option in the product, or explicitly highlight them within the documentation as highly recommended configurations.
    • Practitioner: Leverage practitioners of the products to be the curators of the content.




The Practitioner

Security documentation needs to be built for the security practitioner. Therefore, it is logical to assume that the best people to draft and update documentation are practitioners themselves. The first choice for the SecOps vendor is to have a developer, engineer or sales engineer curate the content.

In many cases, this model can work very efficiently. However, these resources already have a job related to the success of the product and sales processes, and can also fall victim to the trap of deprioritizing documentation. This is where quality influencers can come in and assist.

Influencers are key individuals in the SecOps industry who either know the product directly or can indirectly relay highly technical information in an easily digestible way for users. Many of these influencers are known to the vendor through direct partnerships or their customer channel, while others are known to the industry directly through published content or reputation.

Either way, influencers are practitioners who use the product. As a third party not actually employed by the SecOps vendor, influencers have an edge over internal resources, as they may not necessarily “drink the Kool-Aid” and will relay information from a more authentic perspective than that of the company.

The Outcome

As the SecOps world continues to evolve rapidly, maintaining a high standard of product utilization and customer success is paramount to the very mission of the security vendor. Documentation and support are major components of this success. If SecOps vendors start putting more focus on documentation, I expect the following outcomes.

  • Building of or enhanced trust for end users
  • Reduced support overhead, help desk ticketing and operational costs
  • A drive toward greater customer success and retention
  • Informing customers of new and important updates or best practices
  • Helping customers face the ever-increasing threats facing their environment

The Takeaway

Documentation is an important part of attracting and retaining customers. Proper documentation leads to successful customer implementation. Using influencer practitioners to write documentation increases the quality and perceived value of documentation. This can be accomplished independently or by using documentation services from an influencer marketing company like Fixate.

Note that there is an important side benefit of thorough documentation housed on a company website— improved SEO. For companies like DigitalOcean and HashiCorp, their documentation pages generate the most inbound traffic. For all these reasons, the impact of strong security documentation on customer success, longevity, and attraction makes proper security documentation a must for any successful software company.


Patrick O’Fallon is a Principal at Axiom Group in Denver, Colorado. Serving both public and private organizations, Patrick serves as an outsourced CIO to provide strategic consulting with specialized insight into the ever changing SecOps landscape. A graduate from Regis University with a degree in Computer Science, Patrick has a wide breadth of knowledge to support BiModal ITOps organizations by leveraging DevOps and SecOps expertise combined with over 15 years of ITOps experience. Patrick has consulted in Artificial Intelligence and Advanced Algorithms with various public and private organizations.

Would you like to share your thoughts?

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Subscribe to the Fixate IO Blog Highlights, Amplify

Keep up with the latest Fixate IO blog posts about influencer content marketing for B2B and increasing share of voice.  Sign up here: