Add Front page template for project team documentation spec
Change-Id: Ic665d4ece58b2ab00f2bbe6ee8d21039382a9e4d
This commit is contained in:
parent
1e04477632
commit
62c1fd4b03
@ -48,7 +48,7 @@ For more information about working with gerrit, see
|
|||||||
http://docs.openstack.org/infra/manual/developers.html#development-workflow.
|
http://docs.openstack.org/infra/manual/developers.html#development-workflow.
|
||||||
|
|
||||||
To validate that the specification is syntactically correct (i.e. get more
|
To validate that the specification is syntactically correct (i.e. get more
|
||||||
confidence in the Jenkins result), please execute the following command::
|
confidence in the Zuul result), please execute the following command::
|
||||||
|
|
||||||
$ tox
|
$ tox
|
||||||
|
|
||||||
|
@ -4,6 +4,15 @@
|
|||||||
Documentation Program Specifications
|
Documentation Program Specifications
|
||||||
====================================
|
====================================
|
||||||
|
|
||||||
|
Rocky approved specs
|
||||||
|
====================
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:glob:
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
specs/rocky/*
|
||||||
|
|
||||||
Queens approved specs
|
Queens approved specs
|
||||||
=====================
|
=====================
|
||||||
|
|
||||||
|
241
specs/rocky/front-page-template.rst
Normal file
241
specs/rocky/front-page-template.rst
Normal file
@ -0,0 +1,241 @@
|
|||||||
|
..
|
||||||
|
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||||
|
License.
|
||||||
|
|
||||||
|
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
Front page template for project team documentation
|
||||||
|
==================================================
|
||||||
|
|
||||||
|
Use consistent content structure on the front page across all OpenStack
|
||||||
|
project team documentation hosted on docs.openstack.org.
|
||||||
|
|
||||||
|
Problem description
|
||||||
|
===================
|
||||||
|
|
||||||
|
Actionable feedback gathered at the `Queens PTG docs project meeting`_
|
||||||
|
included requests for the Documentation Project to provide guidance and a set
|
||||||
|
of recommendations on how to structure common content typically found on the
|
||||||
|
front page for project team docs, located at ``doc/source/index.rst`` in the
|
||||||
|
project team repository.
|
||||||
|
|
||||||
|
The goal of this change is to make it easier for users to find, navigate, and
|
||||||
|
consume project team documentation, and for contributors to set up and
|
||||||
|
maintain the project team documentation.
|
||||||
|
|
||||||
|
The recommended template as described in this spec would be included in the
|
||||||
|
`OpenStack Documentation Contributor Guide`_ as part of the project team setup
|
||||||
|
docs. The `Cookiecutter Template for new OpenStack projects`_ would also be
|
||||||
|
updated for changes described in this spec.
|
||||||
|
|
||||||
|
The recommendations for the project team front page would serve as the basis
|
||||||
|
for one of the future governance docs tags. Project teams would use the future
|
||||||
|
docs tag to show the maturity of their documentation and adherence to
|
||||||
|
community recommendations.
|
||||||
|
|
||||||
|
The definition of governance docs tags would be covered in a separate spec.
|
||||||
|
|
||||||
|
Proposed change
|
||||||
|
===============
|
||||||
|
|
||||||
|
The main idea behind the recommended content structure is to outline the
|
||||||
|
content based on target audience groups. The main audience groups are defined
|
||||||
|
as end users, operators, and contributors.
|
||||||
|
|
||||||
|
This template reuses some ideas from the front page of the `OpenStack Compute
|
||||||
|
service`_. Projects are encouraged to make additional changes to the template
|
||||||
|
per their specific needs so long as the design and structure ideas are
|
||||||
|
retained.
|
||||||
|
|
||||||
|
.. code-block:: rst
|
||||||
|
|
||||||
|
=================================================================
|
||||||
|
OpenStack {{service/component name}} ({{codename}}) documentation
|
||||||
|
=================================================================
|
||||||
|
|
||||||
|
.. figure:: images/project-logo.jpg
|
||||||
|
:alt: {{codename}} logo
|
||||||
|
:scale: 40%
|
||||||
|
:align: center
|
||||||
|
|
||||||
|
What is {{codename}}?
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
{{codename}} is the OpenStack {{service/component name}} service/component
|
||||||
|
that does... to solve...
|
||||||
|
|
||||||
|
For end users
|
||||||
|
-------------
|
||||||
|
|
||||||
|
As an end user of {{codename}}, you want to... so that...
|
||||||
|
|
||||||
|
Using {{codename}}
|
||||||
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Contents:
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
user/index
|
||||||
|
|
||||||
|
Using the {{codename}} API
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
* `{{codename}} API <http://developer.openstack.org/api-ref/{{codename}}/>`_
|
||||||
|
|
||||||
|
For operators
|
||||||
|
-------------
|
||||||
|
|
||||||
|
As an operator of {{codename}}, you want to... so that...
|
||||||
|
|
||||||
|
Installing {{codename}}
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Contents:
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
install/index
|
||||||
|
|
||||||
|
Administrating {{codename}}
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Contents:
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
admin/index
|
||||||
|
|
||||||
|
Reference
|
||||||
|
~~~~~~~~~
|
||||||
|
|
||||||
|
Contents:
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
configuration/index
|
||||||
|
cli/index
|
||||||
|
|
||||||
|
Additional resources
|
||||||
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
* `{{codename}} release notes <https://docs.openstack.org/releasenotes/{{codename}}/>`_
|
||||||
|
|
||||||
|
For contributors
|
||||||
|
----------------
|
||||||
|
|
||||||
|
As a contributor to {{codename}}, learn more about how to get started
|
||||||
|
as a contributor... and how to...
|
||||||
|
|
||||||
|
Getting started
|
||||||
|
~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
* `OpenStack Contributor Guide <https://docs.openstack.org/contributors/>`_
|
||||||
|
|
||||||
|
Contributing to {{codename}}
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Contents:
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
contributor/index
|
||||||
|
|
||||||
|
Additional reference
|
||||||
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Contents:
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
reference/index
|
||||||
|
|
||||||
|
Indices and tables
|
||||||
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Contents:
|
||||||
|
|
||||||
|
* :ref:`genindex`
|
||||||
|
* :ref:`modindex`
|
||||||
|
|
||||||
|
Search
|
||||||
|
------
|
||||||
|
|
||||||
|
* :ref:`search`
|
||||||
|
|
||||||
|
Alternatives
|
||||||
|
------------
|
||||||
|
|
||||||
|
#. Do nothing.
|
||||||
|
|
||||||
|
Essentially, maintain the status quo by not providing any guidance on
|
||||||
|
structuring content on the front page besides the ``doc/`` directory
|
||||||
|
structure as defined in `Project guide setup`_ in the OpenStack
|
||||||
|
Documentation Contributor Guide.
|
||||||
|
|
||||||
|
The status quo makes it more difficult for users to find, navigate, and
|
||||||
|
consume project team documentation, and for contributors to set up and
|
||||||
|
maintain the project team documentation.
|
||||||
|
|
||||||
|
#. Structure the front page based on current high-level groupings.
|
||||||
|
|
||||||
|
Consistently organize the content on front pages based on subdirectories in
|
||||||
|
the ``doc/`` directory of each project team repository, such as
|
||||||
|
``install/``, ``contributor/``, or ``configuration/``.
|
||||||
|
|
||||||
|
This might make it difficult for users to navigate the front page if there
|
||||||
|
are too many documents linked from that page.
|
||||||
|
|
||||||
|
Implementation
|
||||||
|
==============
|
||||||
|
|
||||||
|
Assignee(s)
|
||||||
|
-----------
|
||||||
|
|
||||||
|
* Petr Kovar (pkovar)
|
||||||
|
* Documentation team PTL for Stein
|
||||||
|
* Documentation team
|
||||||
|
* Project teams
|
||||||
|
|
||||||
|
Work items
|
||||||
|
----------
|
||||||
|
|
||||||
|
* Update the OpenStack Documentation Contributor Guide with the template.
|
||||||
|
* Update the Cookiecutter Template for new OpenStack projects with the
|
||||||
|
template.
|
||||||
|
* Project teams provide patches for their project team documentation to
|
||||||
|
implement the changes to the front page.
|
||||||
|
|
||||||
|
Dependencies
|
||||||
|
============
|
||||||
|
|
||||||
|
Get a buy-in and commitment from project teams and the OpenStack community
|
||||||
|
to actively implement the changes to project team documentation.
|
||||||
|
|
||||||
|
Testing
|
||||||
|
=======
|
||||||
|
|
||||||
|
Testing would follow the standard review process as defined by project teams.
|
||||||
|
|
||||||
|
References
|
||||||
|
==========
|
||||||
|
|
||||||
|
* `Project guide setup`_
|
||||||
|
* `Cookiecutter Template for new OpenStack projects`_
|
||||||
|
* `OpenStack Documentation Contributor Guide`_
|
||||||
|
* `Queens PTG docs project meeting`_
|
||||||
|
* :doc:`../pike/os-manuals-migration`
|
||||||
|
* `OpenStack Compute service`_
|
||||||
|
|
||||||
|
.. _Project guide setup: https://docs.openstack.org/doc-contrib-guide/project-guides.html
|
||||||
|
.. _Cookiecutter Template for new OpenStack projects: https://git.openstack.org/cgit/openstack-dev/cookiecutter/
|
||||||
|
.. _OpenStack Documentation Contributor Guide: https://docs.openstack.org/doc-contrib-guide/
|
||||||
|
.. _Queens PTG docs project meeting: https://etherpad.openstack.org/p/docs-i18n-ptg-rocky
|
||||||
|
.. _OpenStack Compute service: https://docs.openstack.org/nova/latest/
|
Loading…
Reference in New Issue
Block a user