For a highly technical product like Scylla, the success or failure of its adoption rests heavily in knowledge transfer to the community. Documentation is fundamental to that. To find out what’s new and what’s hot in Scylla documentation, I went to the source and had this exchange with Laura Novich, Senior Technical Writer for ScyllaDB.
Laura, you’re not just a technical writer. You’ve also been a certified Red Hat systems administrator. What are the commonalities, in skills and habits, between being a sysadmin and being a technical writer for a company like ScyllaDB?
When instructing users on systems such as ScyllaDB, you need to think about the entire package. When working on Linux systems there are multiple ways to the same goal, so our documentation needs to respect that. I wasn’t always a technically oriented person, and learning Operating Systems such as RHEL and databases such as Scylla have helped me to understand our users and customers. I am passionate about the OpenSource community and strive to deliver the best instructions for our products. The Scylla Docs team uses the philosophy of the Open Source community to “Publish Early, Publish often.” As such we aim to get documentation out as soon as it is ready. Our documentation is publicly available on our website.
Aside from technology, what other experiences do you bring? How do those experiences impact your technical writing?
In addition to my SysAdmin experience, I have experience in Education where I was an ESL teacher in public schools. This experience helps me understand our users and customer’s needs from a methodological point of view.
My hobbies include cake decorating and writing and I feel these experiences help me break down instructions into small chunks which are easier to understand and help me build use cases which not only are useful for our users, but are easy to follow.
What recent major changes to Scylla documentation do you want to bring readers’ attention to?
In general, we have incorporated an improved search capability to quickly find any information which is stored on our documentation server. On each page, there is also a link you can click to leave feedback about a change or improvement you would like to see. Also this year, we added a Glossary of terminology with terms highlighted throughout the documentation suite.
Specifically, there are pages about the latest Scylla features such as Workload Prioritization, Role Based Access Control, In-memory Tables, Global Secondary Indexes, Materialized Views, Hinted Handoff, Scylla’s Compaction Strategies, and more.
We have extensive CQL pages and examples throughout the documentation suite.
What is your goal when you set out to write documentation for Scylla?
What we strive to do with our documentation is to not only focus on “How to do X”, but also on “Why to do X versus Y” as well as “How to do X better”.
We hope you will find our documentation easy to follow and understand as well as technically accurate and informative.
What are the ten most popular sections in our documentation? And what might you say about each one?
From what I can see:
- Getting Started – If this is your first time installing Scylla, preparing for production, or creating tables with CQL, this is the place to start.
- Scylla for Developers – Has what you need to take your application and integrate it with Scylla as your backend database. Includes Drivers, and Scylla features.
- CQLSh: the CQL shell – command line shell used to interact with Cassandra through CQL (the Cassandra Query Language).
- Scylla for Administrators – Create users, usernames, passwords, give users roles and permissions. Also includes procedures and information about Scylla Manager and Monitoring
- Data Manipulation – CQL commands for reading data from your database, with and without filtering.
- Data Definition – create tables and keyspaces with fully documented CQL commands.
- Best Practices for Running Scylla on Docker – you can run Scylla on a public cloud (AWS, GCE), on-premises (bare metal), and on Scylla Cloud (NoSQL DBaaS) as well, but this focuses on how to run Scylla in a Docker container.
- Scylla Architecture – Scylla under the hood, how Scylla maintains Consistency Availability and Partition tolerance.
- Scylla Ring Architecture – Overview – Part of Scylla Architecture, the ring is the basis for Scylla’s distributed design.
- Data Types – all the data types supported in CQL, from ascii to varint.
What is the best way for our community to get documentation requests, comments or corrections to you?
On the bottom of every page in the documentation suite is the following link:
Clicking on the link opens an issue in Github and automatically sites the page’s origin. There is a form to fill in where you provide us with information about the issue. Click Submit and your issue is submitted. You can follow the issue’s progress, and all our documentation issues, in Github.
All you need to report an issue is a free Github account.
We strive to make our documentation better and hope you will help us in this endeavor by giving us suggestions for improvement. For example, if you have broader comments besides a specific page drop us a line or join our Slack channel. Let your voice be heard!
Thanks very much Laura for your time today, and for maintaining our documentation site, which such a valuable resource to our users.