crate / crate/crate-operator

Documentation available only in raw RST format

Open
#858 2 comments 0 reactions 1 assignee Claimed by @juanpardo View on GitHub
documentation help wanted
Dominant language
Python
Stars
27
Forks
9
Avg merge
3d 1h
Merged PRs (30d)
11

Description

## Problem

There is documentation inside https://github.com/crate/crate-operator/tree/master/docs. However, documentation is in the RST format, meaning it doesn't render in a human-friendly format.

The main README links several times to RST files. For example, to https://github.com/crate/crate-operator/blob/master/docs/source/configuration.rst for reading up on parameters. Since it's raw RST, it doesn't render properly in the browser.

~There does not seem to be a hosted version of the documentation on cratedb.com/docs~. There is documentation hosted at https://crate-operator.readthedocs.io/en/latest/index.html, but it is linked only when clicking on this tiny "docs latest" icon (very hidden):

Image

## Suggestion

The hosted documentation should be prominently linked in the README, and clearly be identifiable as the main documentation.
There should be no links to raw RST files from the README.

Furthermore, the README currently competes with the documentation when it comes to installation. There are detailed installation steps in the README, but only very limited ones in the [documentation](https://crate-operator.readthedocs.io/en/latest/installation.html). I suggest to move it to the documentation.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.