---
layout: docpage

title: "Documentation"

is_homepage: false
is_sphinx_doc: true

doc-parent: "Contributing to Cassandra"

doc-title: "Working on Documentation"
doc-header-links: '
  <link rel="top" title="Apache Cassandra Documentation v4.0-alpha5" href="../index.html"/>
      <link rel="up" title="Contributing to Cassandra" href="index.html"/>
      <link rel="next" title="Jenkins CI Environment" href="ci.html"/>
      <link rel="prev" title="How-to Commit" href="how_to_commit.html"/>
'
doc-search-path: "../search.html"

extra-footer: '
<script type="text/javascript">
    var DOCUMENTATION_OPTIONS = {
      URL_ROOT:    "",
      VERSION:     "",
      COLLAPSE_INDEX: false,
      FILE_SUFFIX: ".html",
      HAS_SOURCE:  false,
      SOURCELINK_SUFFIX: ".txt"
    };
</script>
'

---
<div class="container-fluid">
  <div class="row">
    <div class="col-md-3">
      <div class="doc-navigation">
        <div class="doc-menu" role="navigation">
          <div class="navbar-header">
            <button type="button" class="pull-left navbar-toggle" data-toggle="collapse" data-target=".sidebar-navbar-collapse">
              <span class="sr-only">Toggle navigation</span>
              <span class="icon-bar"></span>
              <span class="icon-bar"></span>
              <span class="icon-bar"></span>
            </button>
          </div>
          <div class="navbar-collapse collapse sidebar-navbar-collapse">
            <form id="doc-search-form" class="navbar-form" action="../search.html" method="get" role="search">
              <div class="form-group">
                <input type="text" size="30" class="form-control input-sm" name="q" placeholder="Search docs">
                <input type="hidden" name="check_keywords" value="yes" />
                <input type="hidden" name="area" value="default" />
              </div>
            </form>
            
            
            <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../getting_started/index.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../new/index.html">New Features in Apache Cassandra 4.0</a></li>
<li class="toctree-l1"><a class="reference internal" href="../architecture/index.html">Architecture</a></li>
<li class="toctree-l1"><a class="reference internal" href="../cql/index.html">The Cassandra Query Language (CQL)</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data_modeling/index.html">Data Modeling</a></li>
<li class="toctree-l1"><a class="reference internal" href="../configuration/index.html">Configuring Cassandra</a></li>
<li class="toctree-l1"><a class="reference internal" href="../operating/index.html">Operating Cassandra</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Cassandra Tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../troubleshooting/index.html">Troubleshooting</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Contributing to Cassandra</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="gettingstarted.html">Getting Started</a></li>
<li class="toctree-l2"><a class="reference internal" href="ide.html">Building and IDE Integration</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html">Testing</a></li>
<li class="toctree-l2"><a class="reference internal" href="patches.html">Contributing Code Changes</a></li>
<li class="toctree-l2"><a class="reference internal" href="code_style.html">Code Style</a></li>
<li class="toctree-l2"><a class="reference internal" href="how_to_review.html">Review Checklist</a></li>
<li class="toctree-l2"><a class="reference internal" href="how_to_commit.html">How-to Commit</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Working on Documentation</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#how-cassandra-is-documented">How Cassandra is documented</a></li>
<li class="toctree-l3"><a class="reference internal" href="#github-based-work-flow">GitHub based work flow</a></li>
<li class="toctree-l3"><a class="reference internal" href="#jira-based-work-flow">Jira based work flow</a></li>
<li class="toctree-l3"><a class="reference internal" href="#working-on-documents-locally-using-sphinx">Working on documents locally using Sphinx</a></li>
<li class="toctree-l3"><a class="reference internal" href="#notes-for-committers">Notes for committers</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="ci.html">Jenkins CI Environment</a></li>
<li class="toctree-l2"><a class="reference internal" href="dependencies.html">Dependency Management</a></li>
<li class="toctree-l2"><a class="reference internal" href="release_process.html">Release Process</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../faq/index.html">Frequently Asked Questions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../plugins/index.html">Third-Party Plugins</a></li>
<li class="toctree-l1"><a class="reference internal" href="../bugs.html">Reporting Bugs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contactus.html">Contact us</a></li>
</ul>

            
          </div><!--/.nav-collapse -->
        </div>
      </div>
    </div>
    <div class="col-md-8">
      <div class="content doc-content">
        <div class="content-container">
          
  <div class="section" id="working-on-documentation">
<h1>Working on Documentation<a class="headerlink" href="#working-on-documentation" title="Permalink to this headline">¶</a></h1>
<div class="section" id="how-cassandra-is-documented">
<h2>How Cassandra is documented<a class="headerlink" href="#how-cassandra-is-documented" title="Permalink to this headline">¶</a></h2>
<p>The official Cassandra documentation lives in the project’s git repository. We use a static site generator, <a class="reference external" href="http://www.sphinx-doc.org/">Sphinx</a>, to create pages hosted at <a class="reference external" href="https://cassandra.apache.org/doc/latest/">cassandra.apache.org</a>. You’ll also find developer centric content about Cassandra internals in our retired <a class="reference external" href="https://wiki.apache.org/cassandra">wiki</a> (not covered by this guide).</p>
<p>Using a static site generator often requires to use a markup language instead of visual editors (which some people would call good news). Sphinx, the tool-set we use to generate our documentation, uses <a class="reference external" href="http://www.sphinx-doc.org/en/stable/rest.html">reStructuredText</a> for that. Markup languages allow you to format text by making use of certain syntax elements. Your document structure will also have to follow specific conventions. Feel free to take a look at <a class="reference external" href="..">existing documents</a> to get a better idea how we use reStructuredText to write our documents.</p>
<p>So how do you actually start making contributions?</p>
</div>
<div class="section" id="github-based-work-flow">
<h2>GitHub based work flow<a class="headerlink" href="#github-based-work-flow" title="Permalink to this headline">¶</a></h2>
<p><em>Recommended for shorter documents and minor changes on existing content (e.g. fixing typos or updating descriptions)</em></p>
<p>Follow these steps to contribute using GitHub. It’s assumed that you’re logged in with an existing account.</p>
<ol class="arabic simple">
<li>Fork the GitHub mirror of the <a class="reference external" href="https://github.com/apache/cassandra">Cassandra repository</a></li>
</ol>
<img alt="../_images/docs_fork.png" src="../_images/docs_fork.png" />
<ol class="arabic simple" start="2">
<li>Create a new branch that you can use to make your edits. It’s recommended to have a separate branch for each of your working projects. It will also make it easier to create a pull request later to when you decide you’re ready to contribute your work.</li>
</ol>
<img alt="../_images/docs_create_branch.png" src="../_images/docs_create_branch.png" />
<ol class="arabic simple" start="3">
<li>Navigate to document sources <code class="docutils literal notranslate"><span class="pre">doc/source</span></code> to find the <code class="docutils literal notranslate"><span class="pre">.rst</span></code> file to edit. The URL of the document should correspond  to the directory structure. New files can be created using the “Create new file” button:</li>
</ol>
<img alt="../_images/docs_create_file.png" src="../_images/docs_create_file.png" />
<ol class="arabic simple" start="4">
<li>At this point you should be able to edit the file using the GitHub web editor. Start by naming your file and add some content. Have a look at other existing <code class="docutils literal notranslate"><span class="pre">.rst</span></code> files to get a better idea what format elements to use.</li>
</ol>
<img alt="../_images/docs_editor.png" src="../_images/docs_editor.png" />
<p>Make sure to preview added content before committing any changes.</p>
<img alt="../_images/docs_preview.png" src="../_images/docs_preview.png" />
<ol class="arabic simple" start="5">
<li>Commit your work when you’re done. Make sure to add a short description of all your edits since the last time you committed before.</li>
</ol>
<img alt="../_images/docs_commit.png" src="../_images/docs_commit.png" />
<ol class="arabic simple" start="6">
<li>Finally if you decide that you’re done working on your branch, it’s time to create a pull request!</li>
</ol>
<img alt="../_images/docs_pr.png" src="../_images/docs_pr.png" />
<p>Afterwards the GitHub Cassandra mirror will list your pull request and you’re done. Congratulations! Please give us some time to look at your suggested changes before we get back to you.</p>
</div>
<div class="section" id="jira-based-work-flow">
<h2>Jira based work flow<a class="headerlink" href="#jira-based-work-flow" title="Permalink to this headline">¶</a></h2>
<p><em>Recommended for major changes</em></p>
<p>Significant changes to the documentation are best managed through our Jira issue tracker. Please follow the same <a class="reference external" href="https://cassandra.apache.org/doc/latest/development/patches.html">contribution guides</a> as for regular code contributions. Creating high quality content takes a lot of effort. It’s therefor always a good idea to create a ticket before you start and explain what you’re planing to do. This will create the opportunity for other contributors and committers to comment on your ideas and work so far. Eventually your patch gets a formal review before it is committed.</p>
</div>
<div class="section" id="working-on-documents-locally-using-sphinx">
<h2>Working on documents locally using Sphinx<a class="headerlink" href="#working-on-documents-locally-using-sphinx" title="Permalink to this headline">¶</a></h2>
<p><em>Recommended for advanced editing</em></p>
<p>Using the GitHub web interface should allow you to use most common layout elements including images. More advanced formatting options and navigation elements depend on Sphinx to render correctly. Therefor it’s a good idea to setup Sphinx locally for any serious editing. Please follow the instructions in the Cassandra source directory at <code class="docutils literal notranslate"><span class="pre">doc/README.md</span></code>. Setup is very easy (at least on OSX and Linux).</p>
</div>
<div class="section" id="notes-for-committers">
<h2>Notes for committers<a class="headerlink" href="#notes-for-committers" title="Permalink to this headline">¶</a></h2>
<p>Please feel free to get involved and merge pull requests created on the GitHub mirror if you’re a committer. As this is a read-only repository,  you won’t be able to merge a PR directly on GitHub. You’ll have to commit the changes against the Apache repository with a comment that will close the PR when the committ syncs with GitHub.</p>
<p>You may use a git work flow like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">remote</span> <span class="n">add</span> <span class="n">github</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">apache</span><span class="o">/</span><span class="n">cassandra</span><span class="o">.</span><span class="n">git</span>
<span class="n">git</span> <span class="n">fetch</span> <span class="n">github</span> <span class="n">pull</span><span class="o">/&lt;</span><span class="n">PR</span><span class="o">-</span><span class="n">ID</span><span class="o">&gt;/</span><span class="n">head</span><span class="p">:</span><span class="o">&lt;</span><span class="n">PR</span><span class="o">-</span><span class="n">ID</span><span class="o">&gt;</span>
<span class="n">git</span> <span class="n">checkout</span> <span class="o">&lt;</span><span class="n">PR</span><span class="o">-</span><span class="n">ID</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>Now either rebase or squash the commit, e.g. for squashing:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">reset</span> <span class="o">--</span><span class="n">soft</span> <span class="n">origin</span><span class="o">/</span><span class="n">trunk</span>
<span class="n">git</span> <span class="n">commit</span> <span class="o">--</span><span class="n">author</span> <span class="o">&lt;</span><span class="n">PR</span> <span class="n">Author</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>Make sure to add a proper commit message including a “Closes #&lt;PR-ID&gt;” text to automatically close the PR.</p>
<div class="section" id="publishing">
<h3>Publishing<a class="headerlink" href="#publishing" title="Permalink to this headline">¶</a></h3>
<p>Details for building and publishing of the site at cassandra.apache.org can be found <a class="reference external" href="https://github.com/apache/cassandra-website/blob/master/README.md">here</a>.</p>
</div>
</div>
</div>


          <div class="doc-prev-next-links" role="navigation" aria-label="footer navigation">
            
            <a href="ci.html" class="btn btn-default pull-right " role="button" title="Jenkins CI Environment" accesskey="n">Next <span class="glyphicon glyphicon-circle-arrow-right" aria-hidden="true"></span></a>
            
            
            <a href="how_to_commit.html" class="btn btn-default" role="button" title="How-to Commit" accesskey="p"><span class="glyphicon glyphicon-circle-arrow-left" aria-hidden="true"></span> Previous</a>
            
          </div>
          
        </div>
      </div>
    </div>
  </div>
</div>