You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 8 Next »

Overview

Google is sponsoring a program called Google Season of Documentation. Here is their description taken from their site:

The goals of Season of Docs are to give technical writers an opportunity to gain experience in contributing to open source projects, and to give open source projects an opportunity to engage the technical writing community.

During the program, technical writers spend a few months working closely with an open source community. They bring their technical writing expertise to the project's documentation, and at the same time learn about open source and new technologies.

The open source projects work with the technical writers to improve the project's documentation and processes. Together they may choose to build a new documentation set, or redesign the existing docs, or improve and document the open source community's contribution procedures and onboarding experience.

Together, we raise public awareness of open source docs, of technical writing, and of how we can work together to the benefit of the global open source community.

The goal of this page is to put together a successful application for Apache Cassandra so we could get a Technical Writer in the community to improve the documentation in Cassandra. Program details are here.


Volunteers

The following people have volunteered to help out with this project. If you'd like to help out, please feel free to add your name. Alternatively, if things have changed on your end, please cross out your name.

Note: Please subscribe to the Google Season of Docs Announce mailing list for updates.

Sr.NameEmail
1Dinesh Joshidjoshi@apache.org
2Nate McCallzznate.m@gmail.com
3Chris Lohfinkclohfink@apache.org
4Ben Slaterben.slater@instaclustr.com
5Rahul Singhrahul.xavier.singh@gmail.com
6Aaron Ploetzaaronploetz@gmail.com
7Horia Mocioia.mocioi@gmail.com
8Stefan Miklosovicstefan.miklosovic@instaclustr.com
9Laxmikant Upadhyaylaxmikant.hcl@gmail.com


Open Source Organization Administrators

TBD. The program requires each Open Source organization to have at least 2 administrators.


Application

Here are some tips to create a successful application. Timeline & Deadlines are available here. Mentoring organizations (us) can start submitting applications as soon as April 2 but the final deadline to get the application in is April 23, 2019.

We need to get together the following -

  • Project Ideas
  • Provide details about working with Technical Writers and Documentation
  • Previous experience working in similar programs such as Google Summer of Code, etc.
  • A link to any material we publish about our participation in GSoD such as a blog post.

Potential Project Ideas

Please feel free to add project ideas below.

  1. Update Cassandra documentation for 4.0 release
  2. Document Cassandra Architecture 2.x, 3.x, 3.0.x, 4.x in detail
  3. Create specific how-to guides for use-cases on Cassandra
  4. Get rid of all TODOs on Cassandra Website (docs)
  5. Operator's Handbook for Cassandra
  6. Detailed nodetool documentation for operators
  7. Common Application Architecture patterns using Cassandra
  8. Improving CQL documentation


Project Descriptions

1 - Apache Cassandra 4.0 Documentation Update

Project Name: Apache Cassandra 4.0 Documentation Update

Project Description: Review and update existing Apache Cassandra documentation to ensure it is aligned with the forthcoming Apache Cassandra 4.0 release. Our proposed approach to this would be firstly, a call to the cassandra-dev mailing list for Cassandra contributors to highlight areas of the document that require update and secondly, a structured review of existing documentation to identify gaps. For example, in the structured review, the technical writer could compare the Cassandra configuration file documentation (http://cassandra.apache.org/doc/latest/configuration/cassandra_config_file.html) with the configuration options actually contained in code (https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/config/Config.java).

Related material:

2 - Cassandra Operator's Handbook

Project Name: Apache Cassandra Operational Handbook

Project Description: Apache Cassandra is a distributed database that is seeking a qualified technical writer to create an extensive operator's handbook. This handbook will cover topics right from Installation to Tuning & Troubleshooting the database. Here are the top level topics we'd like to cover –

  1. Installation
  2. Configuring
  3. Securing
  4. Monitoring
  5. Tuning
  6. Safely restart
  7. Adding, removing, replacing nodes
  8. Upgrading Cassandra
  9. Backing up & Restoring
  10. Expansions, Shrinking & Replacing
  11. Troubleshooting Cassandra
  12. Miscellaneous tools & utilities

This is not an exhaustive list of topics. This is just indicative of the topics we'd like to cover. There might be additional topics that might get added later. The handbook will cover various versions of Cassandra such as 2.x, 3.x, 3.11.x, 4.x pointing out differences between the versions. We estimate that each topic might take anywhere between 1-5 pages to cover the topic. The project will also include adding sample code, commands and illustrations.

Related material:


3 - Improving CQL documentation

Project Name: Apache Cassandra CQL Documentation

Project Description: Apache Cassandra is a distributed database that is seeking a qualified technical writer to create documentation for Cassandra's Query Language (CQL). CQL, like SQL, is a query language that allows users to interact with Cassandra. CQL provides DDL (Data Definition Language), DML (Data Modification Language) & DCL (Data Control Language). CQL has a well defined grammar and syntax which varies with the Cassandra version. This documentation should support Cassandra 2.x, 3.x, 3.11.x, 4.x. There are approximately 40 CQL commands with several options in each. The document should contain example usages for each CQL command as well as how it varies amongst different versions. This could theoretically cover also some core schema design principles and best practices how to design tables in order to achieve best performance and usability.

Related material:


4 - Detailed nodetool documentation for operators

Project Name: Apache Cassandra nodetool documentation for operators

Project Description: Apache Cassandra is a distributed database that is seeking a qualified technical writer to create documentation for Cassandra's nodetool. nodetool is a tool that operators rely heavily on for their day-to-day operations. It is one of the mechanisms that an operator interacts with a node in the cluster. Therefore it is a critical aspect of building & managing a Cassandra cluster. This documentation should support Cassandra 2.x, 3.x, 3.11.x, 4.x. There are approximately 80 nodetool commands with several options in each. The document should contain example usages for each nodetool command as well as how it varies amongst different versions. I would be very nice to have not only "how" but also "why" behind these commands. Operator should know what each command is for and in what circumstances one should consider to use them. There could be a classification or categorisation of related commands to some groups which are covering some part of Cassandra architecture (eg. commands grouping SSTables and so on). There could be some frequent scenarios and workflows using nodetool command to identify, debug and resolve issues with Cassandra cluster when it comes to every-day usage.

Related material:


4 - Resolve TODOs in Apache Cassandra Documentation

Project Name: Resolve TODOs in Apache Cassandra Documentation

Project Description: The Apache Cassandra documentation contains a number of sections highlighted as TODO. These are:

  • Operating Cassandra / Backups
  • Operating Cassandra / Bulk Loading
  • CQL / Data Definitions (limited review points)
  • Data Modelling
  • Dynamo / Gossip, Failure Detection and Token Ring
  • Architecture/Guarantees
  • Operating Cassandra/Hints
  • Architecture/Overview (this is proposed as a separate project)
  • Operating Cassandra/Read Repair

Many in the community have existing material to cover these topics (including public blog posts, etc) so the most productive approach to completing these sections is likely to be to request good references/material from the mailing lists and synthesise into concise document of the Apache Cassandra documentation set.

Related material:














  • No labels