项目团队文档的前页模板

更新日期：2018-12-06 13:55

项目团队文档首页模板¶

在 docs.openstack.org 上托管的所有 OpenStack 项目团队文档的首页使用一致的内容结构。

问题描述¶

在 Queens PTG 文档项目会议上收集到的可操作反馈包括，文档项目需要提供指导和一组关于如何构建项目团队文档首页上常见内容的建议，这些文档位于项目团队仓库中的 doc/source/index.rst 中。

此更改的目标是让用户更容易找到、导航和使用项目团队文档，并让贡献者更容易设置和维护项目团队文档。

本文档中描述的推荐模板将包含在 OpenStack 文档贡献者指南中，作为项目团队设置文档的一部分。 OpenStack 新项目 Cookiecutter 模板也会根据本文档中描述的更改进行更新。

项目团队首页的建议将作为未来治理文档标签的基础。项目团队将使用未来的文档标签来展示其文档的成熟度以及对社区建议的遵守情况。

治理文档标签的定义将在单独的文档中介绍。

提议的变更¶

推荐内容结构背后的主要思想是根据目标受众群体来概述内容。主要受众群体定义为最终用户、操作员和贡献者。

此模板借鉴了 OpenStack 计算服务首页的一些想法。鼓励项目根据其特定需求对模板进行其他更改，只要保留设计和结构思想即可。

=================================================================
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 <https://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`

备选方案¶

什么都不做。

本质上，除了 OpenStack 文档贡献者指南中的 Project guide setup 中定义的 doc/ 目录结构之外，不要对首页内容结构提供任何指导，从而保持现状。

现状使得用户更难找到、导航和使用项目团队文档，并且使得贡献者更难设置和维护项目团队文档。
根据当前的高级分组构建首页结构。

根据每个项目团队仓库的 doc/ 目录中的子目录（例如 install/、contributor/ 或 configuration/）一致地组织首页上的内容。

如果从该页面链接了太多的文档，这可能会使用户难以导航首页。

实现¶

负责人¶

Petr Kovar (pkovar)
Stein 的文档团队 PTL
文档团队
项目团队

工作项¶

使用该模板更新 OpenStack 文档贡献者指南。
使用该模板更新 OpenStack 新项目 Cookiecutter 模板。
项目团队提供补丁，以对其项目团队文档进行更改，从而修改首页。

依赖项¶

获得项目团队和 OpenStack 社区的认可和承诺，以积极实施对项目团队文档的更改。

测试¶

测试将遵循项目团队定义的标准审查流程。

参考资料¶