How to write Scylla knowledge base articles

Topic: Documentation

Learn: How to write knowledge base articles about Scylla

Audience: Scylla and Apache Cassandra developers, tech writers, administrators

We make Scylla knowledgebase articles in Markdown, with Jekyll. This is a sample.

Basic formatting

See the front matter lines at the top of kb-sample.md (between --- lines).

  • permalink must be a unique URL path.
  • tags must include “kb” to be included in knowledge base. To add multiple tags to a page, put each tag on a separate line, prefixed with -
  • layout: doc tells Jekyll to use the documentation template.
  • section: doc sets the section for the top nav.

All kb articles include “kb” in tags, and have “doc” for both layout and section.

Metadata lines such as “Topic:” and “Learn:” should be 4th-level headings (#### in Markdown, <h4> in HTML.)

This is a pointless subhead

This is a sample paragraph about some sample code.

line 1
line 2

To use syntax highlighting for a specific language, use <code> inside <pre>, like this:

sudo systemctl restart scylla

or use Github style code blocks.

def foo
  puts 'foo'
end
#include<iostream>
using namespace std;

int main()
{
    cout << "Hello World" << endl;
}

Bullet lists and tables

  • Bullet lists
    • Regular Markdown
    • Just like the wiki
Table Feature Do we have it? How to do it
table cells Pipe characters
check marks HTML span elements
red Xs HTML span elements
spacer GIFs n/a

Workflow

To preview a change in progress, see README.md at the top level of the web site.

Starting in Git

If you start your document as a new Markdown file, or change to an existing file, follow the GitHub pull request workflow (see References.)

Starting from Google Docs

If your document began as a document in Google Docs, here is a simple way to move it over to GitHub.

  • First, apply basic Markdown for links and code blocks within the Google Docs page. This preserves formatting when copying it over.
  • Put figures in a shared folder with clear names (figure1.png, figure2.png, ...)
  • Start a new branch and add your content. Put a note at the top of the Google Docs page to let people know that it has been moved to Git.
  • Make any needed edits to the Markdown. When you are happy with your changes, push the branch and start a pull request.

References

Knowledge Base