The Stitch docs are now open source!

In December, I led the charge on open-sourcing the Stitch docs. While everyone at Stitch has been able to contribute for a few months, anyone anywhere — even you! — can now propose changes.

Getting to this point has been more than a year in the making. Achieving my end-goal of allowing outside contributions required a lot of changes behind-the-scenes, which I’ll dive into shortly.

Why open source? Why allow contributions? I believe that truly great documentation can only come from collaboration. I wanted to create a culture of collaboration by empowering my colleagues (or Stitches) and now, Stitch users, to share their knowledge.

Culture of collaboration

First off: What does it mean to have a culture of collaboration? To understand this, you also need to understand why documentation is important.

Documentation is crucial to troubleshooting issues, successfully using a product, and creating an inclusive, knowledgeable community. The takeaway from GitHub’s 2017 Open Source Survey says it well:

Documentation is highly valued, frequently overlooked, and a means for establishing inclusive and accessible communities.

I’m a documentation evangelist and, admittedly, an idealist. I like to think that everyone thinks about documentation as often as I do, but that (unfortunately) isn’t the reality, even for my fellow Stitches.

And that’s OK. While it’s my job to live and breathe documentation, the same can’t be said for everyone else. That doesn’t mean contributing to or using the docs has to be difficult or time-consuming, which was too often the case.

To build a culture of collaboration, I needed to remove the barriers to sharing knowledge and ensure contributors were recognized for their efforts.

The docs: a brief history

To understand the present, you need to know the past.

Back in 2015, when Stitch was still part of a company called RJMetrics, I joined the team as the first (and to this day, only) technical writer. Before my arrival, documentation was done ad-hoc and lived wherever the unlucky person writing it felt most comfortable: Google Drive, an internal wiki, Zendesk. Knowledge was everywhere, but without anyone being responsible for it, no one could find it.

My first goal was to consolidate our disparate sources of knowledge into our Zendesk Guide knowledge base. The entire documentation process, from initial request to final deployment, then looked like this:

With a process like this, no wonder the docs were ignoredWith a process like this, no wonder the docs were ignored

While some of these steps may look a bit questionable — why would I think that copying and pasting from a local HTML file was a good idea? — they were all I had to work with at the time. This type of workflow is, unfortunately, fairly common for technical communicators.

After working with Zendesk for a few months, I grew frustrated with how inefficient and cumbersome it was to use. Solutions like Zendesk Guide are a good fit for companies with small amounts of content, but not for those that require more robust technical authoring tools.

Replacing Zendesk

Managing the documentation set for a single product, especially one as extensive as RJMetrics’ BI product, is a full-time job on its own. When we split off into Stitch and my workload ballooned, I began to research replacing Zendesk.

Before I dove into assessing new solutions, I created a list of must-haves that aided in making my decision. Out of all the criteria I used to evaluate platforms, these were the most important:

Easy to use

If extensive coding knowledge was required to make changes — for example, XML — it would exclude a lot of people who might otherwise contribute.

Ability to reuse content

The platform had to support single-sourcing content and allow me to display an article in more than a single category or section.

Due to the lack of single-source support in Zendesk, I had to update content manually in multiple places if something changed, be it a snippet of copy or an entire article. This reduced my productivity and increased the likelihood that articles could become outdated.

Customizable content templates

While Zendesk does allow users to customize the look and feel of their help sites with relative ease, it doesn’t let them customize the way the majority of article content is rendered.

All content had to be manually converted to HTML before being added to the knowledge base because Zendesk’s embedded WYSIWYG editor didn’t always work as expected. Not only did this make it difficult to maintain consistent formatting, it also reduced my productivity.

At the very least, I wanted to be able to use Stitch’s branding. I also wanted more freedom with template customization than most traditional support portals provide.

For example: I wanted to be able to take advantage of conditional content to display certain content only on pages that meet certain conditions.

Flexible content hierarchy

Zendesk supports only three levels of organization, and a single article cannot be used in more than one category, making intuitive content hierarchies difficult to create.

While it’s rare for our content to go more than three levels deep, it does happen. I wanted the ability to do this if needed instead of trying to hack the navigation or shoehorn content into irrelevant places.

Simple preparation and deployment

To hide new content until it was ready to be publicly available, we used Zendesk’s draft feature. If there were several articles involved, each article had to be manually toggled to public. This worked fine for rolling out new content, but with no way to stage changes to live docs, it made rolling changes inefficient.

Updates to existing documentation could make launch day a nightmare: they would occur post-launch and usually take up a good portion of the day, even if the content was coded beforehand. I needed a simpler way to update and deploy content.

Permissioning structure and change history

At the time we were using Zendesk, changes could be made by anyone without being tracked. Without the ability to control editing or see what updates were made, trying to pinpoint who did what and when became a time-consuming task. I needed to be able to approve changes before they went live and see how docs changed over time.

Integrate with Stitch’s support platform

Stitch uses Intercom to handle incoming support requests, so the replacement platform needed to allow us to add custom JavaScript. Out of all the criteria, this one was the easiest to meet.

Over the course of my research, I trialed at least a dozen solutions. I was continually surprised and frustrated by the fact that the majority of products, like Zendesk Guide, treated content management as an afterthought. They seemed to assume that support agents would add and update content as they came across it, not a dedicated documentarian, so certain features weren’t needed. These products effectively ignore people like me whose job is to write and manage knowledge.

Some apps got close to what I wanted but ultimately fell short, either by lacking in features, not being mature enough, or not fitting my use case. While technical documentation products have evolved over the years — take Corilla, Paligo, or even Confluence, if you like a more classic approach — I began to think that I was searching for something that didn’t yet exist.

Then I discovered Jekyll.

Jekyll and docs-as-code

Jekyll is an open source static site generator that uses Liquid (Shopify’s Ruby-based templating language), YAML, and Markdown. It’s free, easy to learn, and highly customizable.

The trend of using products like Jekyll and GitHub to produce and manage documentation is referred to as “docs as code.” This method can allow anyone to contribute while maintaining structure, versioning, and writing standards. Instead of approaching documentation as a thankless, ad-hoc task, docs as code applies development principles to technical documentation, enables easy collaboration, and simplifies the publishing process.

I was smitten. Despite not being a developer and having only minimal coding experience, I found Jekyll to be almost exactly what I was looking for.

There were, however, some downsides.

I’m not a developer

As I had to learn on the fly, this meant that the initial setup and migration from Zendesk took awhile.

Solved by: Learning on the fly and asking tons of questions. Stitch is lucky to have such patient developers.

No built-in search functionality

This is, unfortunately, a pitfall of any static site generator.

Solved by: Implementing a service like Algolia or Swiftype. I opted to go with Algolia’s DocSearch to get things up and running.

Learning curve for nontechnical folks

Moving from a WYSIWYG editor to working with raw files, even in Markdown, was a challenge for a lot of Stitches.

Solved by: Training and documentation. Stitch contributors have become comfortable enough working in GitHub’s UI to make changes.

I might become an information silo

I’m the only person at Stitch with an in-depth knowledge of how our docs work.

Solved by: There isn’t a permanent solution, despite training and documentation. Preventing this is an ongoing effort.

Lack of translation options

This isn’t currently an issue for Stitch, but may become one as we scale and acquire customers outside the United States.

Solved by: Potentially hiring a translation service.

Lack of built-in, non-website output options, such as PDFs

This is also not currently an issue, but it may be if Stitch launches an on-premises offering.

Solved by: Jekyll can support different outputs, but the functionality isn’t out-of-the-box.

Seeing that other companies with similar needs — GitHub, SendGrid, CircleCI, and Wistia to name a few — switched to static site generators and were pleased with the results gave me confidence that things would work.

In the end, despite the downsides, we decided to push ahead and make the leap to Jekyll.

The documentation process, Jekyll-ified

Let’s fast-forward to today and take a look at new documentation process with Jekyll:

The process with Jekyll: no more headachesThe process with Jekyll: no more headaches

Switching to Jekyll allowed us to streamline the documentation process by simplifying some steps and eliminating others. Not only has the new process reduced the amount of time most documentation tasks require, it’s also made it easier for other Stitches to understand how the docs are created and updated.

Highlights: the great

It’s been a little more than nine months since we made the switch to Jekyll. Here’s how I think we’ve made progress.

Everyone feels empowered to make or suggest changes to the docs

Not just engineers, either. Stitches in every department have made pull requests to the docs over the past year. One Stitch said:

This [Jekyll] is a change that helps the whole team. Our documentation process is frictionless and scalable now. I’ve contributed pull requests to the doc site and can assert that the new system is awesome.

Transparency and knowledge retention has improved

Thanks to GitHub’s version control and history, it’s easy to keep track of the specific changes to our docs and who was involved in making them, even if they leave the company.

Farewell, mystery Google doc people
Farewell, mystery Google doc people

Additionally, because documents and comments are no longer lost in the abyss of our Google Drive, we’re able to better retain and share our knowledge over time.

Our review process is more streamlined

Adding colleagues as reviewers on a pull request makes reviewing documentation a breeze. Reviewers can still leave comments in-line and, unlike Google docs, GitHub will notify me when they’ve submitted a completed review.

Bonus: No fiddling with viewing permissions. Since the docs repo is public, everyone can see everything. If additional people are tagged on a pull request, they can see it immediately.

Ah, simplicityAh, simplicity

Updating and managing content is more efficient

Jekyll templates and single-sourcing content mean I can spend less time on formatting and updating docs and more time building dashboards, analyzing doc usage, and implementing improvements.

Drafting an article for a new integration used to take at least an hour. Thanks to content reuse, it now takes minutes. This code, for example:

YAML and Markdown for the setup instructions for Stitch’s HubSpot integrationYAML and Markdown for the setup instructions for Stitch’s HubSpot integration

Creates this:

The rendered content for HubSpot
The rendered content for HubSpot

Launch day panic is (mostly) a thing of the past

I’ve been able to reclaim my time on launch days, as the ability to stage doc changes for release makes deployment dead simple.

This process has also made it easy for my colleagues to push updates if I happen to be out of the office on a launch day.

Sharing doc updates is easier, courtesy of automated notifications via DocBot

To keep the rest of my team in the loop, I created DocBot, a Slack bot powered by a Zapier webhook triggered by merging pull requests.

Instead of manually posting updates in Slack or sending out emails, I can type up a brief summary of the changes, include links, and let Zapier and DocBot take care of the rest:

DocBot

DocBot also shares contributions made by other Stitches when their pull requests are merged:

DocBot

Not only does this notify contributors that their work has been merged, it also lets the other Stitches how awesome that person is for doing it.

Highlights: the yet-to-be-great

While Jekyll has been fantastic to work with, a handful of things could be better.

Despite all I’ve learned, I’m still not a developer

To use Jekyll, I had to (re)teach myself HTML and CSS and learn Liquid, Ruby, and the command line on the fly.

While I’m proficient and can fix most issues, occasionally things will break that require expertise I don’t have. This is rare, but because I’m the type of person who likes to solve problems on my own, it’s still frustrating.

Lack of integration with potential in-app documentation tools

Many of the solutions I found that offered the ability to serve documentation inside an app currently integrate only with services like Zendesk. To do this at Stitch would require building a custom in-house solution, which simply isn’t something we want to do.

Less than stellar search options and maintenance

While Algolia is a solid search option and allowed us to get up and running with Jekyll, I’ve found maintenance to be difficult and cumbersome. I’m not a JavaScript expert and am currently looking for a search solution that doesn’t require scripting knowledge to maintain. (Suggestions are welcome!)

Building a community of contributors

They say it takes a village (to have great documentation). Like others, I expected some hesitance to the idea of open-sourcing our docs and was delighted to be proven wrong. The steps we’ve taken over the past year have helped build a community that actively and regularly participates in curating the docs that support it.

Stitch values transparency and DTRT, or Doing The Right Thing. Enabling anyone to provide feedback, make changes, or see what’s being worked on creates transparency and interactivity in the docs. Open-sourcing Stitch’s docs and sharing the trove of knowledge we’ve accumulated just made sense. It was The Right Thing.

The docs have come a long way since Stitch launched and I’m excited to see what this year brings!

I hope you’ll join the community over in the Stitch docs repo! First-time contributor? No problem! Check out the repo’s contribution guide to get started.