Documentation Communities: Sound Strategy or Documentarian’s Gambit?¶
Sketchnote
Description
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:
- 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.
- Conference: Write the Docs Portland
- Year: 2021
