Documentation Communities: Sound Strategy or Documentarian’s Gambit?

Presented by: Laura Novich, Scylla DB


This year, like many of you, I binged on the Queen’s Gambit. In chess, a gambit is a move where you sacrifice a chess piece in the hope to put yourself in a more advantageous position. When the gambit is presented to the opponent, they can either accept or deny it. If the strategy works for the opponent it is considered to be sound.

Open-sourcing your documentation holds the promise of a huge pool of dedicated volunteer writers, but at the risk of reduced quality and coherence. It is easy to think that more help means less work, but is that really the case? What is the impact on the organization and on the release schedule?

At ScyllaDB, we considered these questions and decided that 2020 was the year to go open. Our code was already open-sourced, but our documentation was not. As the company grew, the docs became harder to manage, especially with only one dedicated technical writer. We considered the risks of how much time we would spend and wondered if it would impact the release cycle. Our solution included recruiting our developers to be active contributors and after we saw this was successful, we open-sourced our documentation. The decisions we made were not simple, we had to endure a painful migration, and we learned many valuable lessons along the way. In the end, we concluded that the time spent gave us a good foundation and we feel we have built an atmosphere where contributors would feel welcome and have created design decisions to make it easy to contribute to docs.

This talk explains how we created a documentation community and created an atmosphere where everyone involved understands their role and is eager to help. Our work is not completely done, but by the time the talk is held, we will have gained enough experience to share what we thought about and what we have learned.

You will receive tips, best practices, examples, and anecdotes that discuss:

Who and Why

This talk is for you if you are thinking about open sourcing your docs or already have. It is even for you if you are a contributor or a documentarian. Anyone who attends will leave with a firm understanding of what needs to be thought about when planning how to create a documentation community. If you have already open sourced the docs, this talk will show potential pitfalls you may have not thought about and will offer solutions to avoid them.

You will receive tips, best practices, examples, and anecdotes that discuss:

  • Recruiting and onboarding contributors: Find new writers and bring them up to speed
  • Keep existing contributors writing: Methods and tools for collaboration, motivation, and reviews with teams inside and outside your organization
  • Get Everyone on-board: How to align the entire organization to think about and contribute to the documentation. Convert the naysayers into cheerleaders.

About our Speaker

Laura Novich entered into technical writing in 1997 and has worked in both start ups and fortune 500 companies in diverse fields such as virtualization, cyber security and enterprise cloud solutions. She is currently the Documentation Manager for Scylla DB, a noSQL startup. Laura is a regular contributor to and is an active member of  Write the Docs in Israel. She is highly recognized for her contributions and maintenance to Fedora’s open source documentation (in KVM).

Laura is a frequent presenter at MEGACOMM, and has had speaking engagements at the Red Hat KVM forum, Scylla Summit, and has attended several hackathons. Laura has won awards for her outstanding collaboration in Red Hat (ExCeed Award), as well as the 3Award for her outstanding documentation project management at 3Com.