Enhance doc contribution guidelines
Enhance greatly the current documentation contribution guidelines and make necessary changes to associated documents. Change-Id: I29ba4ef3a74f183539ada968d48e7c5a2f4ca814
This commit is contained in:
Peter Matulis
parent
efb8decbd6
commit
727fa10975
18
README.md
18
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].
|
||||
|
||||
<!-- LINKS -->
|
||||
|
||||
[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
|
||||
|
|
|
|||
|
|
@ -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 <doc-style-guide>` for the OpenStack
|
||||
Charms project.
|
||||
The writing format is Markdown. Please see the :doc:`Writing style guide
|
||||
<doc-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 <contact>`
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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 <contact>` 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 <contact>`.
|
||||
|
||||
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 <doc_sources_summary>` 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 <charm-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 <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
|
||||
|
|
|
|||
|
|
@ -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 <doc_sources_summary>`.
|
||||
|
||||
* `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 <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:]]$" <file>
|
||||
|
||||
To view whitespace with the Vim editor, edit ``~/.vimrc``:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
set listchars=tab:>-,trail:·,eol:$
|
||||
nmap <silent> <leader>w :set nolist!<CR>
|
||||
|
||||
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
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 64 KiB |
Loading…
Reference in New Issue