[jira] [Created] (CASSANDRA-16029) Create better Apache Cassandra 4.0 docs

["Lorina Poland (Jira)" <ji...@apache.org>]

Lorina Poland created CASSANDRA-16029:
-----------------------------------------

             Summary: Create better Apache Cassandra 4.0 docs
                 Key: CASSANDRA-16029
                 URL: https://issues.apache.org/jira/browse/CASSANDRA-16029
             Project: Cassandra
          Issue Type: Improvement
          Components: Documentation/Website
            Reporter: Lorina Poland
            Assignee: Lorina Poland
         Attachments: CurrentDocs.png, NewImprovedDocs.png

The proof of concept to create new Documentation showed that a combination of the static site generator (SSG) Antora + Asciidoc files would provide the most flexibility in redesigning the Apache C* OSS pages.

Current proof of concept: [https://polandll.github.io/site/Cassandra/4.0/]

To update the docs, the tools to write needed an update, too, to provide a better UX and modern look and feel. The old tools (reStructured Text, Sphinx) will be replaced with the new tools ([AsciiDoc|http://asciidoc.org], [Antora|http://antora.org]). 

See the attachments for screenshots of the current docs and the POC docs.

The advantages of asciidoc+antora:
 * Rich markdown language that is directly editable.
 * Good organizational structure for docs files
 * Flexible build/publishing capabilities, including content from multiple repositories and branches
 * Flexible web UI, built separately from the doc files and static site.
 * JS extensions that enable additional functionality.

To complete the conversion, the following steps are required:
 * Pandoc used for conversion of rSt files to adoc files
 ** Followed by significant manual editing to fix the errors left over after conversion
 * Creation of new antora files (site.yml, antora.yml, CSS and layout)
 ** Integration with plug-ins (lunr for search, tabs for additional codeblock capabilities)
 ** Finish the UI to match current Apache C* UI, or engage designer to do a new design
 *** Put the ASF pulldown in the main header banner, like Apache Spark does ([https://spark.apache.org/downloads.html])
 * Modification of build scripts to work with Antora
 ** Modification of python scripts that generation YAML and nodetool docs
 *** Make sure that these scripts are run for each version
 ** Modification of cassandra/doc Makefile 
 ** Dockerfile and docker-entrypoint.sh files to use Docker for documentation build
 * Modification of cassandra-website to work with Antora
 ** Dockerfile and docker-entrypoint.sh files to use Docker for documentation build
 * Figure out how to handle older versions that are not converted to asciidoc now
 ** Put in TBD? Copy 4.0 branch with note to rewrite later?
 * Figure out why tabs-block antora extension is working locally but not in GH pages (may or may not be important)

Other tasks:
 * Complete conversion, plus editing the current docs before Apache C* 4.0 GA
 * Further improvements for docs organization 
 ** [https://docs.google.com/document/d/1aeNtgyPAsKcNa0GSKvl2ywlFEj30714ry4Sb5turWeE/edit?usp=sharing]
 ** Get some sections out of Docs, like Developing Code info -> Community
 * Solve the issue of CQL highlighting/lexer/parser issue
 ** Need CQL to be submitted to pygments
 * Addition of more useful documentation - tutorials, how-to guides, separate reference guide

Current work: [https://github.com/polandll/cassandra/blob/doc_redo_asciidoc/|https://github.com/polandll/cassandra/blob/doc_redo_asciidoc/doc/Dockerfile]

 



--
This message was sent by Atlassian Jira
(v8.3.4#803005)

---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cassandra.apache.org
For additional commands, e-mail: commits-help@cassandra.apache.org