Move administrator guide to project repos
The number of approved OpenStack projects continues to grow while the documentation team resources are shrinking. We need a new approach to maintain the high quality of the OpenStack documentation set. This specification proposes allowing project teams to manage their administrator guide content similar to how the api-ref and installation guides are being managed. Change-Id: I70592f5c8a415dc1454a89f1012ad50178359953
This commit is contained in:
johnsom
Stephen Finucane
parent
ec388af66b
commit
4d20a0afd4
|
|
@ -0,0 +1,177 @@
|
|||
..
|
||||
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||
License.
|
||||
|
||||
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||
|
||||
========================
|
||||
Distributed Admin Guides
|
||||
========================
|
||||
|
||||
The growth of the number of OpenStack projects that are administered by an
|
||||
operator base continues to grow. With growth and resource sharing in mind, we
|
||||
want to ensure that the quality of an OpenStack administrator guide remains
|
||||
high. To meet this goal, we think it's best to distribute the maintenance of
|
||||
the source doc files within the project team's repositories.
|
||||
|
||||
This specification proposes allowing project teams to manage their
|
||||
administrator guide content similar to how the api-ref and installation guides
|
||||
are being managed.
|
||||
|
||||
Problem description
|
||||
===================
|
||||
|
||||
Currently there are over sixty approved OpenStack projects. It is unreasonable
|
||||
to expect the documentation team to maintain the administrator guide for all
|
||||
of these projects. We need to optimize the usage of the documentation teams
|
||||
resources.
|
||||
|
||||
Currently the administrator guide is in a seperate git repository from the
|
||||
code and patches being proposed. This leads to an "out of site, out of mind"
|
||||
scenario where updates to the administrator guide are an afterthought if they
|
||||
get updated at all.
|
||||
|
||||
Proposed change
|
||||
===============
|
||||
|
||||
This specification proposes managing the administrator guide similar to the
|
||||
installation guide, where the administrator guide contents are stored in the
|
||||
project repository and are directly managed by the project team. The
|
||||
documentation team can continue to provide an editorial role for the contents
|
||||
of the administrator guide by posting patches to the guide contents in the
|
||||
project repositories. This would allow for the continued consistent quality
|
||||
and voice of the guide.
|
||||
|
||||
Existing administrator guide content would be migrated to the designated
|
||||
project repositories. Project teams can decide which repository is appropriate
|
||||
for the content, for example neutron may choose openstack/neutron-lib. Inside
|
||||
these repositories the administrator guide content will be stored in a well
|
||||
known and consistent location: admin-guide/source. The current administrator
|
||||
guide is already laid out by service/project so this proposal should have
|
||||
minimal impact to the look and feel of the guide.
|
||||
|
||||
Ownership of the project specific administrator guides is with the
|
||||
respective project team, not the documentation team. This means the
|
||||
content is in an existing or new repository owned by the project team,
|
||||
reviews will be done by the project team, and bug reports will go in
|
||||
the bug queue of the project.
|
||||
|
||||
The documentation team enables the project team to write the
|
||||
project specific guides with mentoring, setting up needed
|
||||
infrastructure, writing guidelines, provision of a template ("cookie
|
||||
cutter"), and providing a working base administrator guide that the project
|
||||
specific guides can use as reference.
|
||||
|
||||
The documentation team will select a list of priority projects for the release
|
||||
series that will get a full review and scrub of the administrator guide
|
||||
contents for those selected projects. This is similar to how the i18n team
|
||||
prioritizes projects for localization.
|
||||
|
||||
To publish the project's administrator guide, the project will implement a tox
|
||||
target to build the guide, similar to the one created for the installation
|
||||
guides (see References). A gate job template 'admin-guide-jobs' will be added
|
||||
to the project including the service name. This will cause the administration
|
||||
guide to be published when updates are merged.
|
||||
|
||||
This publication mechanism should be similar that of the installation guide.
|
||||
|
||||
The administrator guide should be structured:
|
||||
|
||||
::
|
||||
|
||||
[openstack-docs/admin-guide/index.rst]
|
||||
====================
|
||||
Administrator Guides
|
||||
====================
|
||||
|
||||
Compute service (nova)
|
||||
======================
|
||||
|
||||
The Compute service ...
|
||||
|
||||
Installation is documented at
|
||||
http://docs.openstack.org/project-admin-guide/pike/compute
|
||||
|
||||
Loadbalancer service (octavia)
|
||||
======================
|
||||
|
||||
The Loadbalancer service ...
|
||||
|
||||
Installation is documented at
|
||||
http://docs.openstack.org/project-admin-guide/pike/loadbalancer
|
||||
.
|
||||
|
||||
[nova/admin-guide/source/index.rst]
|
||||
=======
|
||||
Compute
|
||||
=======
|
||||
* System architecture
|
||||
* Images and instances
|
||||
...
|
||||
|
||||
One difference with the administrator guide from the installation guide is
|
||||
that all of the administrator guides are listed on one page. This makes it
|
||||
easier for users to find any of the official OpenStack project administrator
|
||||
guides.
|
||||
|
||||
With this change the administrator guide will now be versioned by release to
|
||||
allow version specific content. This will be handled the same way the
|
||||
installation guide is versioned. Administrator guides built from master will
|
||||
be published to "draft" while stable branches will publish to the respective
|
||||
release directory.
|
||||
|
||||
::
|
||||
|
||||
The master branch of octavia would publish to:
|
||||
http://docs.openstack.org/project-admin-guide/draft/loadbalancer
|
||||
|
||||
The stable/pike branch of octavia would publish to:
|
||||
http://docs.openstack.org/project-admin-guide/pike/loadbalancer
|
||||
|
||||
Alternatives
|
||||
------------
|
||||
|
||||
1. Do nothing and attempt to maintain a centralized documentation repository.
|
||||
2. Create a documentation repository for each project with shared core status.
|
||||
3. Follow the proposed changes, but allow the documentation team core status.
|
||||
|
||||
Implementation
|
||||
==============
|
||||
|
||||
Assignee(s)
|
||||
-----------
|
||||
Alexandra Settle (asettle)
|
||||
Joseph Robinson (jrobinson)
|
||||
Michael Johnson (johnsom)
|
||||
Ildiko Vancsa (ildikov)
|
||||
Brian Moss (Docs tools)
|
||||
Entire documentation team
|
||||
|
||||
|
||||
Work Items
|
||||
----------
|
||||
* Setup a wiki page to track the transition.
|
||||
* Setup cookiecutter for the administrator guide.
|
||||
* Encourage the project teams to move existing content to project team
|
||||
repositories.
|
||||
* Update the master index file to reflect the new structure.
|
||||
* Write a base administrator guide.
|
||||
* Setup gate jobs to publish the administrator guide on patch merge.
|
||||
* Update the Documentation Contributor Guide to include the required steps
|
||||
to setup a project administrator guide.
|
||||
* Notify project teams when this method of publishing the project specific
|
||||
administrator guide is available.
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
Testing
|
||||
=======
|
||||
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
* https://etherpad.openstack.org/p/docs-i18n-ptg-pike-repos
|
||||
* https://github.com/openstack/docs-specs/blob/master/specs/newton/project-specific-installguides.rst
|
||||
* https://docs.openstack.org/contributor-guide/project-install-guide.html
|
||||
Loading…
Reference in New Issue