From 3acee39f53b41fb49573b4173873f028b23024fe Mon Sep 17 00:00:00 2001 From: Petr Kovar Date: Tue, 24 Oct 2017 20:16:37 +0200 Subject: [PATCH] [contrib] Add team vision doc As drafted in: https://etherpad.openstack.org/p/docs-i18n-ptg-queens-mission-statement Change-Id: If3f7cb397e13b006b50a1fdaf528c94830e2c4ec --- doc/doc-contrib-guide/source/index.rst | 1 + doc/doc-contrib-guide/source/team-vision.rst | 110 +++++++++++++++++++ 2 files changed, 111 insertions(+) create mode 100644 doc/doc-contrib-guide/source/team-vision.rst diff --git a/doc/doc-contrib-guide/source/index.rst b/doc/doc-contrib-guide/source/index.rst index d50ae7c245..7d51096582 100644 --- a/doc/doc-contrib-guide/source/index.rst +++ b/doc/doc-contrib-guide/source/index.rst @@ -23,6 +23,7 @@ Contents quickstart.rst team-structure.rst + team-vision.rst non-native-english-speakers.rst blueprints-and-specs.rst project-guides diff --git a/doc/doc-contrib-guide/source/team-vision.rst b/doc/doc-contrib-guide/source/team-vision.rst new file mode 100644 index 0000000000..bd6328126f --- /dev/null +++ b/doc/doc-contrib-guide/source/team-vision.rst @@ -0,0 +1,110 @@ +.. _team_vision: + +=================================== +2017/2018 documentation team vision +=================================== + +Objective +~~~~~~~~~ + +To craft the individual pieces of our vision process into a singular document +in order to set goals over the next 12 months. + +.. note:: + + This document was written from a futuristic perspective. + +Background +~~~~~~~~~~ + +During the Queens PTG, the OpenStack documentation team outlined four critical +areas for improvement in our processes. These areas include documenting use +cases, setting expectations, improving content visibility, and contributing to +documentation. + +Looking back over the last year since, we made positive progress in all four +areas. Though there is still much work to be done, we have a lot to be proud +of! + +Use cases +~~~~~~~~~~ + +In conjunction with the documentation team, the OpenStack Foundation set up a +new Contributor Portal (``openstack.org/community``), which is a choose your +own adventure for interested user types, such as operators, users, and +contributors. Users select the type of activity they are interested in and are +able to quickly navigate to the appropriate documentation. + +In addition, a new set of high-level common use-case documents (for example, +how to use Gerrit and how to sign up for a project) are available, which +detail step-by-step instructions for common tasks to integrate with the +OpenStack community. This resulted in a net increase on the last user survey +with regards to the OpenStack documentation and its effectiveness for the +community. + +The OpenStack documentation team met with a majority of project teams in Secret +Name of Next PTG Location to offer assistance and guidelines on developing +topic-based documentation with high-level descriptions of OpenStack projects, +supported by realistic, cross-community and outcome-specific use cases. Use +cases are consistent across projects, following unified information +architecture. + +Projects first provided a minimum of three defined use cases, then they +developed content for the use cases and checked the use cases into their +project's repository. The documentation team measured success by reviewing +statistics of the most popular use cases and plans to add additional content +to support them during the next cycle. + +Setting expectations +~~~~~~~~~~~~~~~~~~~~ + +Over the past year we have seen three positive reviews from the trade press +or analyst community on the quality of the OpenStack documentation. Project +teams own and maintain their own content and have worked with the i18n team +to ensure documents are translatable. Project teams, via their project +liaisons, followed the planning process set up by the documentation team to +define use cases. Each code commit in the project repository includes +documentation, if applicable. We successfully added to the release calendar +a window for a set of content reviews with each project liaison, per the +project's needs. Project teams have followed updated Governance documentation +`tag guidelines `_ when +managing their content. + +Content visibility +~~~~~~~~~~~~~~~~~~ + +Within the last development cycle, the documentation team was able to improve +search engine results through improved search engine optimization (SEO) and +content shaping. The most common search terms, as defined by Google +Analytics, are returning timely and relevant results and correctly pointing +back to the appropriate document on ``docs.openstack.org``. + +In an effort to address problems with new and potential users, the +documentation team worked in conjunction with the OpenStack Foundation, the +OpenStack Wiki team, and ``ask.openstack.org`` to create consistent messaging +across all of our properties to ensure users are correctly directed to the +new Contributor Portal or the particular project's documentation on +``docs.openstack.org``. Our success metric seen a 10% increase in positive +responses from both the COA exam takers and the comments on the user survey. +Additionally, we had increased traffic (> 20%) to ``docs.openstack.org``, +which showed greater utilization by the community. + +Finally, a more comprehensive documentation archiving lifecycle was +implemented for releases. Archived content is still available to users who +need it, but we have added CSS overlays to help avoid confusion and ensure it +is clear when legacy content is being viewed. This addressed problems +reported by both COA exam takers and operators using older releases that were +unable to access older documentation. + +Contributing to documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The documentation team collaborated with the Upstream Institute to help +improve mentoring and training aimed specifically at new contributors. A set +of training materials was designed by the documentation team to provide +guidelines for the Upstream Institute volunteer mentors. Two mentors were +chosen to work with the new group of contributors during the OpenStack Summit +and PTG, in addition to the onboarding sessions hosted at the Summit. The +mentors encouraged the new contributors to utilize their new knowledge of +project teams to actively contribute documentation back to the respective +project teams.