Though it is rarely the shiniest, most exciting, or most innovative part of a software product, documentation most definitely has an impact.
You can be sure that a poorly documented product (I’m sure anyone reading this can think of at least a few examples) makes a distinct impression on users as they flail about in a frustratingly shallow, contradictory, incomplete mess of tautologies. I will never recommend the product with documentation that instructed me to “Click Install to install” and left me to figure out the dependencies on my own.
Similarly, good documentation can have a tremendous impact on a user’s experience. Well-written, thoughtfully-curated documentation engages users and encourages learning. It gets to the point and gives the user clear directions without muddying the text with tangents or tangles of cross-links. It provides useful, relevant guidance with the precise amount of detail that helps a user become successful in completing their task or solving their problem. Plus code snippets; lots of code snippets. In the end, a great product may gather attention, but great product documentation gathers promoters.
At Sqreen, we champion great documentation and we offer our recent investment in a Docs Refresh Project as proof. In this post, we’re going to share a bit about our philosophy on documentation, and the steps we’ve taken to refresh and maintain our documentation into the future.
What makes great documentation: our philosophy
Our philosophy, when it comes to documentation, is rooted in our mission to help customers be productive and confident using the Sqreen product. Productive customers are happy customers and that is certainly what we want.
You see, documentation is not a stand-alone entity, a chore to complete by a certain date, a burden to write, and a punishment to read. Documentation is an evolving part of the product. It teaches, and engages, and sells by not selling. Its structure and language serve to enlighten and encourage users as they explore our product. And importantly, it demands that we put ourselves in our users’ shoes, to see what they see as they install, configure, customize, and troubleshoot. As a smart DevOps Engineer once said, “If it doesn’t answer my question or solve my problem, I’m not going to read it.” We have to focus on making that user, and users like her, happy.
We can certainly be proud of this grand docs philosophy, but in practice, keeping our docs in a state that makes our customers productive, confident, and happy was not always easy.
From philosophy to reality
After years of devoting our attention to building our products, our team, our brand, and our customer base, building our docs was not always our top priority. There’s no shame in admitting that-– like every start-up we made decisions that involved trade-offs and we had to prioritize some things over others. The real shame would be if, when we stopped to take a breath, we did not acknowledge that the trade-offs had taken their toll and our documentation was in need of attention. In early 2020, we decided it was time to make some changes, and chose to invest in massive improvements.
We started by listening. Our customers had excellent opinions to offer when we asked them about our documentation. Our newly-onboarded Sqreeners offered really valuable insight into what was missing from our docs as they thoroughly read and re-read the material in an effort to deeply learn our product. And our Sales team made it known that we had a few gaps in our docs. (Those were not the exact words they used, but we got the message.) With that data in hand, a few brave souls in our Marketing and Product Engineering teams volunteered to lead the project to fill in the gaps and refresh our documentation.
A few months later, with the help of a contractor (Janet Revell, who co-wrote this post), and many patient developers and customers, we released our revised and revitalized Sqreen documentation.
To meet our commitment to our docs philosophy and mission, we held ourselves to a high standard: we didn’t want fill-in-the-gap documentation that simply checked the “Done” box, we wanted clear, open, unvarnished content that really lived up to Sqreen’s overall mission of being open, honest, and clear. In a world of black-boxed software, Sqreen seeks to share all the inner-workings of our product because that is what our customers want. We heard you, and that is what we did with our documentation.
The most comprehensive and most sought-after material is what we tackled first. How Sqreen Works was challenging to produce from scratch but has yielded excellent feedback. Allowing readers a peek under the hood of our software makes them confident in purchasing it and productive in using it.
We wrote completely new documentation that describes how to Protect your app with Sqreen. Exhaustive in its detail, we needed to make sure that our users, and potential users, knew what Sqreen was doing when it was protecting apps from attack.
We took on the low-level chores of reorganizing content, normalizing the format of step-by-step procedures, ridding ourselves of the evil of FAQs, establishing and following a style guide, and editing every bit of content to make sure it had the same voice, the same level of accuracy, and the same commitment to our mission.
Our Security Automation Playbook material got an overhaul, our Integration section got a top-to-bottom refresh, and we scrubbed our docs clean of “filler content”. Our grand project to give our documentation the attention it had long been owed was complete and our customers were, indeed, happy.
Documentation is never done
As with software product development (or security), our work on documentation is never really done. As long as the product lives and breathes, so too must the docs, evolving with the product and our audience, adapting to new value propositions, new markets, and new features. And we will never truly be 100% free of typos. It keeps us humble.
The project to refresh our docs had a start and an end date, but the commitment to keep our customers productive, confident, and happy, and the work to keep that commitment, will always be a challenge we’re eager to embrace.
Got an opinion on our docs? See something that you like and want to see more of? We’d love to hear from you at feedback@sqreen.com
—-
This post was co-written with Janet Revell, the fantastic contractor that we worked closely with to iterate and improve our documentation.
