Brief

This guide documents the creation and review process for content that is published on the Apache Cassandra blog and content that is developed and pitched to external press outlets. 

Note: the guide does not currently include social media work. 

Background

At the start of 2021, the blog was mostly a monthly overview called ‘Changelog’, which provided a way to publicize what was happening inside the project by highlighting the latest releases, mailing list threads, votes, ecosystem news, Cassandra news stories, tutorials, and case studies. The production of content slowly grew during 2021 to weekly contributions with a target publication each Tuesday. The current goal moving into 2022 is to publish three to four blogs each month on a regular weekly cadence (see Pipeline Overview for details, below).

Content Goals

The overall goal of producing content for the Apache Cassandra project is to:

  1. Educate & inform - Share the technical knowledge of the many experts in the community as a ‘springboard’ for further investigation in the documentation website and via communication avenues, such as the Slack channels and mailing list.
  2. Increase Reach - Increase the visibility of the Apache Cassandra project and its ecosystem around the project to the industry at large, to existing and potential users & operators.
  3. Celebrate Community - highlight the contributions of community members, committers, and users as unique individuals with expertise and talents.
  4. Foster Collaboration - encourage community members from disparate organizations to develop vendor-neutral Cassandra content for the project itself that would interest users and potential users.

We have established four themes for Apache Cassandra content to help achieve these goals and ensure that a good balance of content is produced:

  1. Community - Content that highlights events, such as ApacheCon, Apache Cassandra World Parties, community presentations, industry initiatives (e.g., Google Summer of Code) as well as explanations of key developments and decisions.
  2. Feature/Technical - Content that explains new features developed, or in development, and technical overviews. The aim is to both promote aspects of Apache Cassandra externally (including pitching to press outlets) and encourage deeper assessments by potential users through the documentation site.
    Note: Recent social media results indicate that the Feature/Technical theme also needs to incorporate more troubleshooting & monitoring guidance, which will also enable us to better achieve our Educate & Inform goal.
  3. Inside Cassandra - Content that takes the form of interviews or first-person accounts of users and contributors sharing how they use Apache Cassandra, their contributions to the project, and comments on the industry and current trends.
  4. Changelog - A monthly regular update on the project, covering the latest dev discussions, the status of features (CEPs), news coverage, tutorial/how-to coverage, and case studies.

Community Helpers

Several community members contribute to the content process:

  • Ekaterina Dimitrova  - Early Reviewer and Community Reviewer & social media.
  • Anthony Grasso - Final Reviewer/Committer, and Antora platform admin.
  • Ben Lerer - Final Reviewer/Committer & social media.
  • Erick Ramirez - Early Reviewer, PR Reviewer, Staging Sanity Checker, Final Reviewer/Committer (as of February 2022).
  • Chris Thornett -  Writes and contributes content based on themes above including the monthly Changelog blog. Maintains the community editorial calendar and coordinates with content contributors from draft stage to publishing stage. Oversees production of the content (up to the community approval stage). Chris also assists with the development of articles that are pitched externally to press sites and researches and develops case studies.
  • Diogenese Topper - Converts community approved drafts to asciidoc and creates pull requests for blog posts, shepherds PRs through to staging making any amendments required by PR Reviewers and Staging Sanity Checkers.
  • Mick Semb Wever - website admin and Final Reviewer/Committer.
  • Various community members - a number of community members review content contributions, during the 72-hour community review stage (see below) on an ad hoc basis.

Apache Cassandra Blog Content Pipeline

Content Planning

Content that is being proposed, researched, and produced currently resides on the Apache Cassandra Project Blog Topics & Content Pipeline Google doc.

This document is open to all community members to ensure transparency and visibility and includes a number of tabs, the most important are:

C* blog community topics - This is a list of topics constructed by the community detailing what content they want to see developed for the blog and potentially for external publication on relevant press sites. 

Note: This list should be reviewed by the community for 2022 and updated with suggestions.

Content Pipeline (blog) - This is the pipeline dashboard indicating the status of blog content once a writer has been assigned through to publication.

Content Pipeline (external) - This dashboard indicates the status of external content once a writer has been assigned through to when it is published by an outlet.

Proposed third-party and other content (pre-pipe) - This tab is research on content that could be used after revision work or repurposed with the permission of third parties. This has been a way to encourage collaboration from organizations active in the ecosystem while publishing vendor-neutral content that is relevant when there hasn’t been any available.

Pipeline Overview

The initial stages of content development tend to be flexible and depend on the type of content being produced. For example, a community writer may assign themselves to a topic and write an initial draft but request developmental editing assistance from Constantia or may prefer only copy editing before their content goes to community review. Inside Cassandra series interviews involve research/fact-finding and approaches to individuals and organizations followed by at least one subject-matter expert call for a draft to be created. 

While the drafting process is quite fluid, once content is drafted it follows the current flow:

1. Draft Review - A writer submits draft content to Constantia (Melissa Logan, Diogenese Topper & Chris Thornett) and it is reviewed for adherence to:

  • Apache Foundation requirements (particularly in regard to vendor neutrality)
  • Grammar, punctuation, and spelling
  • Correct asciidoc formatting, as required by the Antora platform for the build/publishing stage, and appropriate blog template structure 
  • Technical accuracy

If the content isn’t supplied as a Google Document, a new document is created to allow ease of comments and editing. If the content is sufficiently technical it undergoes a peer review. 

2. Technical Peer Review - Where more advanced technical knowledge is required, it is given to either a relevant community SME and/or Ekaterina Dimitrova or Erick Ramirez to review. The timeframe for this is dependent on the availability of reviewers.

3. Community Review - Once the peer review is complete. The Constantia team supplies a link to the Google Document on both the #cassandra-website Slack channel and the dev.cassandra.apache.org mailing list and provides details of the content. A review clock starts at this point consisting of a 72-hour review via lazy consensus. Google Documents are set to ‘comments allowed’ by ‘all’ so that the community can flag issues and Constantia can make any required amendments.

4. Conversion Stage - Once all amendments are made and the 72-hour review period expires, Constantia performs a further proof, checks the asciidoc formatting, and converts the approved content to .adoc format.

5. Jira & Pull Request - Constantia crafts a Jira ticket and creates a Pull Request. The Jira ticket is opened by Constantia and a patch is submitted making reference to the PR on the Jira ticket. Finally, Constantia asks for a Pull Request review on the #cassandra-website Slack channel.

6. Pull Request Approval - Three working days have been requested for the completion of any Pull Request approvals for content. The steps are as follows:

    1. Pull Request Review - The Pull Request is reviewed by a PR reviewer (usually Erick Ramirez). If required, the PR Reviewer makes suggested changes (Erick tends to supply screenshots in Slack as well).

The PR Reviewer (according to Erick Ramirez’s advice) should look at the following:

        • The document header metadata (title, date, categories) contains the correct information.
        • Headers and content are formatted correctly in asciidoc.
        • All hyperlinks are valid and working. 
        • All website links are not hardcoded; pages are referenced with xref: or link: asciidoc macros.
        • Embedded elements such as videos and social media posts are formatted correctly.
        • No missed typos and/or grammatical errors.

b. Pull Request Changes - if required, any suggested changes on the PR are dealt with by Constantia. 

c. Local Docker Run - when needed, a local docker run is performed to do final QA testing.

Note: step 6c, as of 02/21/22,  is waiting on some fixes where local generation isn't identical to how CI is generating it: see CASSANDRA-17374

d. Content PR Approval - The PR is approved by a Project Committer and committed to trunk.

7. Staging & Sanity Check - Once the content is committed to trunk, which is automatic, it is pushed to staging (cassandra.staged.apache.org). There is a final check on staging but this should not be considered part of the review process, but as a Sanity Check before a Project Committer pushes the blog post live.

The Staging Sanity Check (usually by Erick) to ensure it is rendering correctly on the page. (Again, if Erick is reviewing he supplies a screenshot in the #cassandra-website Slack channel.)

8. Final Sanity Check & Publication The post undergoes a final Sanity Check by a Project Committer and, as they have the authority to publish, the website. If there are any changes at this stage, the process returns to Step 6b, and changes are made by Constantia (Note: sometimes a Project Committer offers to make the changes themselves). Once the post is live, the publication is announced on the #cassandra-website Slack channel to allow for promotion on social media.

 Note: The review period, as it stands, from the start of the community review to publication is a minimum of six days. Therefore content drafts have to be ready a week in advance of publication.

Where Help is Needed

More content writers - The project needs more content writers that are willing to submit content, particularly technical blogs, to an agreed deadline and work within the content development process so that chaos doesn’t ensue. The list of topics in the Apache Cassandra Project Blog Topics & Content Pipeline Google doc would be a good starting point.

More reviewers - To reduce the current lengthy approval process, content needs more reviewers on different timezones that are able to work with Jira and GitHub.

More committers that help with content - As per reviewers, we need more committers on different timezones that are capable of performing the web development work to stage, review and publish content. As of February 2022, Anthony Grasso, Lorina Poland & Erick Ramirez accepted committer status, which may have resolved this issue, but this will need assessing over the next 3 months to confirm.

More interviewees - To be able to produce a healthy number of interviews for a series, we need more community members and users willing to be interviewed.




  • No labels