Front page template for project team documentation

updated: 2018-12-06 13:55

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.

=================================================================
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

  1. 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.

  2. 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.

updated: 2018-12-06 13:55
Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

questions?

docs-specs