diff --git a/README.md b/README.md index 491d08de..e259b261 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![tags][image-badge-cg]][image-link-openstack-tags] The [OpenStack Charm Guide][cg] is the main source of information for the -the [OpenStack Charms][openstack-charms]. +[OpenStack Charms][openstack-charms]. ## Building @@ -16,22 +16,22 @@ can be opened individually with a web browser or hosted by a local web server. ## Contributing -Documentation issues can be filed on [Launchpad][lp-bugs-cg]. - This repository is under version control and is managed via the [OpenStack Gerrit system][gerrit-openstack] (see the [OpenDev Developer’s -Guide][opendev-dev-guide]). For specific guidance on working with the -documentation hosted on [docs.openstack.org][link] please read the [OpenStack -Documentation Contributor Guide][openstack-doc-guide]. +Guide][opendev-dev-guide]). The [Documentation contributions][cg-doc-contrib] +page outlines how to contribute to this project. + +## Bugs + +Documentation issues can be filed on [Launchpad][lp-bugs-cg]. [image-badge-cg]: https://governance.openstack.org/tc/badges/charm-guide.svg [image-link-openstack-tags]: http://governance.openstack.org/tc/reference/tags/index.html -[cg]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide +[cg]: https://docs.openstack.org/charm-guide [openstack-charms]: https://launchpad.net/openstack-charms [lp-bugs-cg]: https://bugs.launchpad.net/charm-guide/+filebug [gerrit-openstack]: https://review.openstack.org [opendev-dev-guide]: https://docs.openstack.org/infra/manual/developers.html -[openstack-doc-guide]: https://docs.openstack.org/doc-contrib-guide/index.html -[link]: https://docs.openstack.org +[cg-doc-contrib]: https://launchpad.net/openstack-charms/latest/community/doc-contrib.html diff --git a/doc/source/community/charm-readme-template.rst b/doc/source/community/charm-readme-template.rst index a6e38e62..6eb9fed8 100644 --- a/doc/source/community/charm-readme-template.rst +++ b/doc/source/community/charm-readme-template.rst @@ -12,12 +12,8 @@ the collection of charms. It also helps to reduce the amount of effort needed during the commit review phase (for both author and reviewer) when new charms are developed. -The writing format is Markdown, which can be validated using a `Markdown -viewer`_. The README also gets rendered on the charm's landing page in the -`Charmhub`_ (with the `Mistune`_ Python parser). - -Please see the :doc:`Writing style guide ` for the OpenStack -Charms project. +The writing format is Markdown. Please see the :doc:`Writing style guide +` for the OpenStack Charms project. General approach ---------------- @@ -30,10 +26,12 @@ Any surplus documentation should be submitted to the `OpenStack Charm Guide`_ and then linked to (i.e. "For more information see..."). :doc:`Ask ` for advice if you're unsure about how to submit this sort of documentation. -When referencing another charm in a general way, link to the charm's Charmhub -entry. When referring specifically to information in another charm's README, -link directly to the file, or to a header in the file, by way of the charm's -repository on `opendev.org`_. +When referencing another charm in a general way, link to the charm's +`Charmhub`_ entry for the most recent stable channel (e.g. +https://charmhub.io/keystone?channel=xena/stable). When referring specifically +to information in another charm's README, link directly to the file, or to a +header in the file, by way of the charm's repository on `opendev.org`_ (e.g. +https://opendev.org/openstack/charm-keystone/src/branch/stable/xena/README.md). Structure --------- @@ -291,8 +289,6 @@ Put all links at the bottom. For example: .. LINKS .. _Charmhub: https://charmhub.io .. _opendev.org: https://opendev.org/explore/repos?tab=&sort=recentupdate&q=charm- -.. _Markdown viewer: https://jbt.github.io/markdown-editor -.. _Mistune: https://mistune.readthedocs.io/en/latest .. _OpenStack Charm Guide: https://docs.openstack.org/charm-guide .. _rabbitmq-server: https://opendev.org/openstack/charm-rabbitmq-server/src/branch/master/README.md#high-availability .. _swift-proxy: https://opendev.org/openstack/charm-swift-proxy/src/branch/master/README.md diff --git a/doc/source/community/doc-contrib.rst b/doc/source/community/doc-contrib.rst index 5eba803d..25e988b4 100644 --- a/doc/source/community/doc-contrib.rst +++ b/doc/source/community/doc-contrib.rst @@ -2,15 +2,213 @@ Documentation contributions =========================== -Documentation for the OpenStack Charms project uses the docs-as-code -model where the source text is maintained under version control (Git). The -repositories are listed below. If your unsure on how to go about contributing -to this documentation don't hesitate to ask questions (see the :doc:`Contact -us ` page). +Documentation for the OpenStack Charms project uses the `Docs as Code`_ model +where the source text is maintained under a version control system, Git in this +case. -* `OpenStack Charm Guide`_ (this guide) -* `OpenStack Charms Deployment Guide`_ +If at any time you are unsure about how to contribute to the documentation do +not hesitate to :doc:`ask us questions `. + +Documentation as software criteria +---------------------------------- + +When software is developed certain documentation criteria must be met in order +for the software to be considered feature complete. And like software, a +documentation contribution must be implemented correctly. + +The practice of modelling one's contribution on existing pages can be +counter-productive as the documentation set may not always be in an ideal +state. Therefore, first establish *what* you want to add and then, based on the +available sources, determine *where* to place it and *how* to do so. + +There is a logical order to this document's contents. Please go through it +sequentially. + +Diátaxis +~~~~~~~~ + +The `Diátaxis framework`_ is used throughout the documentation wherever +appropriate. It provides a conceptual approach to writing, which in turn +affects how documentation is created and how a set of pages is organised. +Becoming familiar with Diátaxis is the first step to contributing. + +.. figure:: ../media/diataxis.png + :scale: 80 % + :alt: The four Diataxis quadrants + + The four quadrants of Diátaxis + +.. note:: + + Charmed OpenStack documentation prefers the term "Concepts" in the place of + "Explanations". + +Further reading: a `conference talk`_ - PyCon Australia 2017 + +Monolithic vs distributed +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Now that the Diátaxis framework is understood we can consider what form a +contribution can take. It should be clear that a contribution need not be a +monolithic piece of work; it can be distributed. For instance, on the same +general topic, there can be several interconnected parts such as a conceptual +treatment, a howto guide, and a tutorial. Speak to colleagues, discuss with +your local documentarian, or chat on the user forum. + +Sources +~~~~~~~ + +Assuming that the specific pieces of work have been identified they each need +to be published in the appropriate location, with the right tools, and in the +correct format. The following sub-sections provide an outline of each +documentation source. A :ref:`table ` summarising these +sources is given in the next section. + +OpenStack Charm Guide +^^^^^^^^^^^^^^^^^^^^^ + +The `OpenStack Charm Guide`_ is the main source of information for the +OpenStack Charms project. All Diátaxis types are therefore appropriate: +Tutorials, Howtos, Concepts, and Reference. The Charm Guide also includes +community and project information - categories that fall outside of the +Diátaxis framework. + +This documentation is created on `OpenDev`_, is under version control (Git), +and is written in `Sphinx-enhanced reStructuredText`_. + +OpenStack Charms Deployment Guide +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The `OpenStack Charms Deployment Guide`_ is the main source of information for +the charm-by-charm deployment of a Charmed OpenStack cloud. Due to its focussed +nature, the only suitable Diátaxis type is Howtos. + +This documentation is created on OpenDev, is under version control (Git), and +is written in Sphinx-enhanced reStructuredText. + +.. note:: + + The Deploy Guide is currently in the process of migrating non-deployment + related content to the Charm Guide. + +OpenStack Charms Admin Guide +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The `OpenStack Charms Admin Guide`_ is the day-2 operations guide for Charmed +OpenStack. Due to its focussed mandate, the only applicable Diátaxis type is +Howtos. + +This documentation is created on OpenDev, is under version control (Git), and +is written in Sphinx-enhanced reStructuredText. + +.. note:: + + The Admin Guide is currently embedded in the Charm Guide. The intention is + to eventually break it out into a separate guide. + +Charm READMEs +^^^^^^^^^^^^^ + +A charm README file specifically encapsulates a charm's purpose and usage +(Diátaxis is not applied). + +In order to maintain a consistent structure across all charms, a :doc:`README +template ` has been made available and should be +followed. + +This documentation is created on OpenDev, where each charm has its own +repository (see `OpenStack charms`_), and is written in Markdown. A README also +gets rendered on the its charm's landing page in the `Charmhub`_ (with the +`Mistune`_ Python parser). See the `keystone charm`_ for an example. + +.. tip:: + + The rendering of a README (into HTML) can be validated with a `Markdown + viewer`_. + +Charm developer documentation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Charm developer documentation is written by developers and for developers. It +may include topics such as how to build, enhance, test, or debug a charm. +Conceptual documentation that explains the inner workings of a charm is another +possibility. Suggested Diátaxis types are Howtos and Concepts. + +This documentation is created in Discourse (essentially CommonMark) and is +viewed in the Charmhub. See the `keystone charm Docs tab`_ for an example. + +.. _doc_sources_summary: + +Sources summary +~~~~~~~~~~~~~~~ + +.. list-table:: **Summary of documentation sources** + :header-rows: 1 + :widths: 22 12 8 8 15 + + * - Published + - Domain + - Platform + - Format + - Diátaxis + + * - `OpenStack Charm Guide`_ + - docs.openstack.org + - OpenDev + - Sphinx RST + - Tutorials, Howtos, Concepts, Reference + + * - `OpenStack Charms Deployment Guide`_ + - docs.openstack.org + - OpenDev + - Sphinx RST + - Howtos + + * - `OpenStack Charms Admin Guide`_ + - docs.openstack.org + - OpenDev + - Sphinx RST + - Howtos + + * - charm READMEs + - charmhub.io + - OpenDev + - Markdown + - n/a + + * - charm developer documentation + - charmhub.io + - Discourse + - Markdown + - Howtos, Concepts + +Writing style +~~~~~~~~~~~~~ + +Please use the :doc:`style guide ` when creating content. +Documentation is more clearly understood by users and developers alike when it +is implemented in a consistent manner. + +Technical accuracy +~~~~~~~~~~~~~~~~~~ + +The contribution needs to be technically correct. In particular, if the content +is a Howto or a Tutorial then the collection of steps must be tested and +verified. .. LINKS -.. _OpenStack Charm Guide: https://opendev.org/openstack/charm-guide/src/branch/master/README.md -.. _OpenStack Charms Deployment Guide: https://opendev.org/openstack/charm-deployment-guide/src/branch/master/README.md +.. _Docs as Code: https://www.writethedocs.org/guide/docs-as-code +.. _Diátaxis framework: http://diataxis.fr +.. _conference talk: https://youtu.be/t4vKPhjcMZg +.. _OpenStack Charm Guide: https://docs.openstack.org/charm-guide +.. _OpenStack Charms Deployment Guide: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide +.. _OpenStack Charms Admin Guide: https://docs.openstack.org/charm-guide/latest/admin +.. _OpenStack charms: https://opendev.org/openstack?q=charm&tab=&sort=recentupdate +.. _Charmhub: https://charmhub.io +.. _Markdown viewer: https://jbt.github.io/markdown-editor +.. _Mistune: https://mistune.readthedocs.io/en/latest +.. _keystone charm Docs tab: https://charmhub.io/keystone/docs +.. _keystone charm: https://charmhub.io/keystone +.. _OpenDev: https://opendev.org +.. _Sphinx-enhanced reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html +.. _CommonMark: https://spec.commonmark.org diff --git a/doc/source/community/doc-style-guide.rst b/doc/source/community/doc-style-guide.rst index 3b1c2ce5..c26b1ac4 100644 --- a/doc/source/community/doc-style-guide.rst +++ b/doc/source/community/doc-style-guide.rst @@ -5,31 +5,18 @@ Writing style guide Overview -------- -This guide describes the writing style that is applied to the OpenStack Charms -project documentation: +This guide describes the writing style for the OpenStack Charms documentation +:ref:`sources `. -* `OpenStack Charm Guide`_ -* `OpenStack Charms Deployment Guide`_ -* `OpenStack charms`_ (README files) +.. note:: -Both the above guides are published using the `Sphinx`_ documentation -generator. As such, enhanced `reStructuredText`_ (RST) formatting is used. + The OpenStack Charms project also abides by these guides: -The charm README files are formatted in Markdown. The :doc:`Charm README -template ` provides guidance on how to produce a README -file. + * the `OpenStack documentation contributor guide`_ + * the `Ubuntu documentation style guide`_ -Other resources -~~~~~~~~~~~~~~~ - -The below resources contain a wealth of information that can also be of use: - -* the `Canonical documentation style guide`_ -* the `OpenStack documentation contributor guide`_ - -In general, the OpenStack Charms project abides by these guides. However, in -cases of disagreement or ambiguity the current document takes precedence over -them. + However, in cases of disagreement or ambiguity, the current document takes + precedence. General guidelines ------------------ @@ -135,28 +122,11 @@ All extra whitespace should be removed, especially at the end of lines. Two trailing spaces is valid Markdown; it forces a carriage return. This is very rarely required and should be avoided whenever possible. -To check a file for trailing spaces (tested with Bash and Zsh): - -.. code-block:: none - - grep -n "[[:space:]]$" - -To view whitespace with the Vim editor, edit ``~/.vimrc``: - -.. code-block:: none - - set listchars=tab:>-,trail:·,eol:$ - nmap w :set nolist! - -The default leader character is the backslash, so toggle your whitespace -goggles with :command:`\\w` while in command mode. - Snippets -------- Some messaging is used repeatedly due to situations that arise regularly. This section is an attempt at making a consistent set of snippets for such cases. -Use the appropriate RST or MD formatting. Preview charms or functionality ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -839,11 +809,7 @@ An image as hyperlink: [image-target-link]: link URL .. LINKS -.. _OpenStack Charm Guide: https://docs.openstack.org/charm-guide/latest/ -.. _OpenStack Charms Deployment Guide: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/ -.. _OpenStack charms: https://github.com/orgs/openstack-charmers/repositories?q=charm-&type=&language=&sort= -.. _Canonical documentation style guide: https://docs.ubuntu.com/styleguide/en +.. _Ubuntu documentation style guide: https://docs.ubuntu.com/styleguide/en .. _OpenStack documentation contributor guide: https://docs.openstack.org/doc-contrib-guide .. _Sphinx: https://www.sphinx-doc.org/en/master/index.html -.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html .. _RST documentation on images and figures: https://docutils.sourceforge.io/docs/ref/rst/directives.html#images diff --git a/doc/source/media/diataxis.png b/doc/source/media/diataxis.png new file mode 100644 index 00000000..0631e4a0 Binary files /dev/null and b/doc/source/media/diataxis.png differ