Snyk documentation: Our journey so far

As the manager of Snyk user documentation for the past three years, I’ve overseen many improvements in our user docs.

Contribution culture

We have implemented a unique contribution culture for our user docs. Our documentation has hundreds of active contributors in Snyk, who are continuously creating, updating, and improving content.

One of the main ways we’ve done this is by adopting a docs-as-code process in our documentation team.

Docs-as-code

Put simply, a “docs-as-code” process means that the writing process mirrors the code development process, and typically adopts developer-friendly platforms and tools. For example, Snyk docs use the Gitbook platform, which uses a Git-like set of processes for changes, has a simple editing UI, and syncs with a GitHub repository for content stored in markdown files. 

This process has fully enabled contributions. Removing the steep learning curve and access restrictions associated with professional authoring tools, allows more people to work on content, without facing prohibitive licensing costs.

How Snyk does docs 

At Snyk, our development teams write the first draft of docs for a new feature in the GitBook writing environment. This gives them ownership and engagement, enabling them to quickly contribute to the content, without manual porting and reformatting from other sources. Beginning documentation development before features enter testing means our docs are often ready and published by the time the feature enters the Closed Beta phase, giving our users quick and easy access to information.

We train, support, and encourage all our contributors, giving them in-edit assistance (using the Grammarly tool), and ensuring that all reviews and changes are standardized. Each new R&D team member receives targeted guidance and assigned writers to ensure they know how to contribute, and how to ask for help. Early assistance and automation are key to ensuring good scaling of docs — which is why it’s emphasized in the Snyk approach.

Simply put, Snyk follows two approaches:

• Shift-left: Test your code earlier — as you write it, not just before you release it.

• Shift-down: Get developers to do the testing, rather than specialized security teams. 

Our documentation processes follow this same model. Collaboration, scaling, and automation are in our cultural DNA.

Contribution culture achievements

By transforming the way Snyk creates documentation, as of early 2024, we have over 250 active contributors.  And over the past two years, we’ve made over 6,000 changes and improvements to our docs — nearly 10 changes each day.

Staff are engaged and involved, and tech writers are rightly seen as feature enablers, not blockers. We have avoided last-minute rushes to write up a feature, which can either delay the release or provide poor-quality documentation (or both).

What we’re doing: User experiences, types, and opinions

We are now focusing on improving our documentation's quality, matching Snyk user experiences and types, and providing more “opinionated” prescriptive content.

Matching user experiences

We’re currently transforming our documentation’s information architecture. We have always provided clear “descriptive” documentation to tell users how to use Snyk products. However, we provide little “prescriptive” documentation, to recommend good practices or provide detailed examples. Our users had to work out their own implementation paths without such guidance since the documentation structure wasn’t matched to user experiences, journeys, or personas. 

Where we started

Here’s our 2022 structure, which focused on Snyk products:

Describing the journey

We now have a simplified, targeted information architecture that maps to the user’s linear experience:

Our content journey includes:

• Initial sections that describe the first part of the user experience (“onboarding”), including a Quickstart for evaluation of functions, and an Implement Snyk section for more high-level planning of your business implementation.

• We then describe the details of integrations with Snyk, including Git integrations to link your source code management repositories to Snyk initially, and CI/CD integrations for longer-term deployment strategies.

• We continue with day-to-day operations of Scanning with Snyk, including using each of the Snyk products (such as Snyk Open Source)

• We include general administration tasks described in the Snyk Admin section.

• We finish with descriptions of two self-contained areas — CLI and API

Matching user types 

We have found several types of Snyk users that frequently access our documentation — developers, administrators/implementors, and AppSec staff. 

Each user type has different information requirements, so we want to ensure that our documentation is easy to access and navigate for all these personas, with access to the specific content areas that make the most sense.

For example:

• Developers: We provide Quickstart and Scan with Snyk content

• Administrators/implementors: Can focus on Enterprise configuration and Snyk Admin

• Application Security: Focuses on the Managing Risk

Being more opinionated

We have developed a large body of knowledge over the years on how to help customers successfully implement Snyk, from onboarding to day-to-day usage. This “opinionated” content includes detailed use cases, step-by-step walkthroughs, recommendations, and other prescriptive content. We are collating this body of knowledge and publishing this content.

This content will help all users plan each stage of their Snyk experience. In addition, we know that our growing enterprise market requires more of this type of content, to give them scalable, accessible training materials to ensure they can run an efficient Snyk onboarding program for their own businesses.

We have started this content creation with the Snyk implementation guides in the Implement Snyk section.

Our next steps

Our docs journey is far from complete. 

We are starting and planning many exciting docs projects for 2024, including:

• Adding consistent “story-telling” elements throughout the docs for our customers to use as templates.

• Incorporating helpful AI in the user experience to provide quick answers to your questions.

• Embedding content closer to the user experience, giving you quicker and smarter access to help.

• Adding a consistent and detailed changelog covering all Snyk functional changes.

• Enhancing and publishing a full Error Message catalog.

So keep an eye on the docs for more details!