94 lines
3.5 KiB
ReStructuredText
94 lines
3.5 KiB
ReStructuredText
========================
|
|
Documentation Guidelines
|
|
========================
|
|
|
|
These are some basic guidelines for contributing to documentation in nova.
|
|
|
|
Review Guidelines
|
|
=================
|
|
|
|
Documentation-only patches differ from code patches in a few ways.
|
|
|
|
* They are often written by users / operators that aren't plugged into daily
|
|
cycles of nova or on IRC
|
|
|
|
* Outstanding patches are far more likely to trigger merge conflict in Git than
|
|
code patches
|
|
|
|
* There may be wide variation on points of view of what the "best" or
|
|
"clearest" way is to say a thing
|
|
|
|
This all can lead to a large number of practical documentation improvements
|
|
stalling out because the author submitted the fix, and does not have the time
|
|
to merge conflict chase or is used to the Gerrit follow up model.
|
|
|
|
As such, documentation patches should be evaluated in the basic context of "does
|
|
this make things better than the current tree". Patches are cheap, it can
|
|
always be further enhanced in future patches.
|
|
|
|
Typo / trivial documentation only fixes should get approved with a single +2.
|
|
|
|
How users consume docs
|
|
======================
|
|
|
|
The current primary target for all documentation in nova is the web. While it
|
|
is theoretically possible to generate PDF versions of the content, the tree is
|
|
not currently well structured for that, and it's not clear there is an audience
|
|
for that.
|
|
|
|
The main nova docs tree ``doc/source`` is published per release, so there will
|
|
be copies of all of this as both the ``latest`` URL (which is master), and for
|
|
every stable release (e.g. ``pike``).
|
|
|
|
.. note::
|
|
|
|
This raises an interesting and unexplored question about whether we want all
|
|
of ``doc/source`` published with stable branches that will be stale and
|
|
unimproved as we address content in ``latest``.
|
|
|
|
The ``api-ref`` and ``api-guide`` publish only from master to a single site on
|
|
`developer.openstack.org`. As such, they are effectively branchless.
|
|
|
|
Guidelines for consumable docs
|
|
==============================
|
|
|
|
* Give users context before following a link
|
|
|
|
Most users exploring our documentation will be trying to learn about our
|
|
software. Entry and subpages that provide links to in depth topics need to
|
|
provide some basic context about why someone would need to know about a
|
|
``filter scheduler`` before following the link named filter scheduler.
|
|
|
|
Providing these summaries helps the new consumer come up to speed more
|
|
quickly.
|
|
|
|
* Doc moves require ``.htaccess`` redirects
|
|
|
|
If a file is moved in a documentation source tree, we should be aware that it
|
|
might be linked from external sources, and is now a ``404 Not Found`` error
|
|
for real users.
|
|
|
|
All doc moves should include an entry in ``doc/source/_extra/.htaccess`` to
|
|
redirect from the old page to the new page.
|
|
|
|
* Images are good, please provide source
|
|
|
|
An image is worth a 1000 words, but can go stale pretty quickly. We ideally
|
|
want ``png`` files for display on the web, but that's a non modifiable
|
|
format. For any new diagram contributions we should also get some kind of
|
|
source format (``svg`` is ideal as it can be modified with open tools) along
|
|
with ``png`` formats.
|
|
|
|
Long Term TODOs
|
|
===============
|
|
|
|
* Sort out our toctree / sidebar navigation
|
|
|
|
During the bulk import of the install, admin, config guides we started with a
|
|
unified toctree, which was a ton of entries, and made the navigation sidebar
|
|
in Nova incredibly confusing. The short term fix was to just make that almost
|
|
entirely hidden and rely on structured landing and sub pages.
|
|
|
|
Long term it would be good to reconcile the toctree / sidebar into something
|
|
that feels coherent.
|