From 1fdc8d90303cb7993edbeb566dc7e6df51223f12 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Thu, 30 Nov 2017 10:42:24 -0500 Subject: [PATCH] remove docs:follows-policy tag No teams or deliverables are using the tag and the documentation team wants to reframe it based on the change to having project teams own more of their documentation. Change-Id: I60beb5b191137f3108ddfd002cb2d0ed59deb446 Signed-off-by: Doug Hellmann --- reference/tags/docs_follows-policy.rst | 112 ------------------------- reference/tags/index.rst | 8 -- 2 files changed, 120 deletions(-) delete mode 100644 reference/tags/docs_follows-policy.rst diff --git a/reference/tags/docs_follows-policy.rst b/reference/tags/docs_follows-policy.rst deleted file mode 100644 index b18f4ae05..000000000 --- a/reference/tags/docs_follows-policy.rst +++ /dev/null @@ -1,112 +0,0 @@ -:: - - This work is licensed under a Creative Commons Attribution 3.0 - Unported License. - http://creativecommons.org/licenses/by/3.0/legalcode - -.. _`tag-docs:follows-policy`: - -=================== -docs:follows-policy -=================== - -This tag indicates that a deliverable’s documentation set is prepared in -coordination with the OpenStack Documentation team, and follows their defined -practices and policies for review and verification. It does not indicate that -the documentation team has taken ownership of producing the documentation for -the deliverable. - -Application to current deliverables -=================================== - -.. tagged-projects:: docs:follows-policy - -Rationale -========= - -At present, the documentation team is responsible for all documentation in the -openstack/openstack-manuals repo. Maintaining this documentation requires basic -knowledge of all of the projects covered by the guides. However, being able to -successfully maintain some of the more in-depth knowledge that is written in the -guides is out of scope for the technical writers to handle on their own. -Previously, the documentation team has worked alongside project -teams to collaborate and share knowledge to ensure that the manuals document -all necessary major bug fixes and enhancements. This approach no longer -ensures that the documentation is sufficiently verified by the teams each -release. - -The "docs:follows-policy" tag indicates that project teams are -coordinating with the documentation team, so that contributions, bug reports, -and timely reviews happen over the course of each release cycle. Detailed -expectations are described in the doc-tag section of the Documentation -Contributors' Guide: https://review.openstack.org/453642 . - -The documentation team recommends that project teams who maintain -project-specific guides inside of the openstack-manuals repository (such as, -nova, neutron, cinder, horizon, glance, and keystone), including teams -maintaining projects outside of the starter-kit set, and deployment projects, -apply for this tag. Having the tag indicates that the project teams commit -to provide accurate documentation every release. In these cases, the -documentation team will review the project team's guides, but won't -necessarily contribute significantly to ongoing maintenance. - -Requirements -============ - -The structure outlined by the doc team in their policy -(https://review.openstack.org/453642) is to be loosely followed, dependent on -project circumstance. - -For all teams: - -1. The team must `designate a liaison `_ - to the documentation team. - -For project teams with deliverables covered by guides that are maintained by the -documentation team: - -1. The project team must provide summaries of new features, configuration changes, - etc. that need to be reflected in the documentation. -2. The documentation liaison must follow the published review schedule, read the - documentation, and open bugs appropriately, either providing information - to the docs team on how to document these issues or submitting patches to fix them. - -For project teams with deliverables covered by documentation that is not maintained -by the documentation team: - -1. The project team must prepare their documentation using the standard tool set - provided by the documentation team, and ensure the guides are published to - docs.openstack.org. -2. The project team must prepare and update their documentation following - the published review schedule, and coordinate with the documentation team - to ensure that a review is performed. -3. The project team must actively manage their documentation, handling bug reports - and publishing corrections as needed. -4. The project team must make the documentation team aware of any major changes to the guides - that will impact the way the guides are published. - -Tag application process -======================= - -The tag will be applied for the first time for the Pike release. - -Members of project teams who want the tag associated with their deliverables -should apply for it by adding it to the deliverables they want to cover. - -The documentation team PTL must approve the tag to show that the documentation -team agrees that the relevant guides have been reviewed appropriately by the -review deadline for each cycle as indicated by this tag. - -The tag is applied to deliverables in the governance repository. Each manual -for a deliverable covered by the tag will be annotated to indicate the level -of input or review from the documentation team so that users can easily -discover who is responsible for maintining the content. - -Deprecation -=========== - -This tag will be removed from deliverables when the required coordination -and reviews are not performed for a cycle. Any existing documents annotated -as having been reviewed will not be affected. A project team can re-apply -to have the tag for the following cycle, after the relevant reviews are -performed. diff --git a/reference/tags/index.rst b/reference/tags/index.rst index 04677a6c4..acf06e4c8 100644 --- a/reference/tags/index.rst +++ b/reference/tags/index.rst @@ -79,11 +79,3 @@ Stable Maintenance Tags :maxdepth: 1 stable_follows-policy - -Documentation Tags -================== - -.. toctree:: - :maxdepth: 1 - - docs_follows-policy