For a highly technical product like ScyllaDB, 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 ScyllaDB 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 ScyllaDB 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 ScyllaDB 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 ScyllaDB 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 ScyllaDB features such as Workload Prioritization, Role Based Access Control, In-memory Tables, Global Secondary Indexes, Materialized Views, Hinted Handoff, ScyllaDB’s Compaction Strategies, and more.
Each product such as ScyllaDB Manager and ScyllaDB Monitoring Stack also have dedicated content. In addition to our features and products, we have documentation on Tools and Drivers.
We have extensive CQL pages and examples throughout the documentation suite.
What is your goal when you set out to write documentation for ScyllaDB?
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 ScyllaDB, preparing for production, or creating tables with CQL, this is the place to start.
- ScyllaDB for Developers – Has what you need to take your application and integrate it with ScyllaDB as your backend database. Includes Drivers, and ScyllaDB features.
- CQLSh: the CQL shell – command line shell used to interact with Cassandra through CQL (the Cassandra Query Language).
- ScyllaDB for Administrators – Create users, usernames, passwords, give users roles and permissions. Also includes procedures and information about ScyllaDB 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 ScyllaDB on Docker – you can run ScyllaDB on a public cloud (AWS, GCE), on-premises (bare metal), and on ScyllaDB Cloud (NoSQL DBaaS) as well, but this focuses on how to run ScyllaDB in a Docker container.
- ScyllaDB Architecture – ScyllaDB under the hood, how ScyllaDB maintains Consistency Availability and Partition tolerance.
- ScyllaDB Ring Architecture – Overview – Part of ScyllaDB Architecture, the ring is the basis for ScyllaDB’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.