openstack/openstack-manuals
Code Issues Proposed changes

[contrib] Add team vision doc

Browse Source 
As drafted in:
https://etherpad.openstack.org/p/docs-i18n-ptg-queens-mission-statement

Change-Id: If3f7cb397e13b006b50a1fdaf528c94830e2c4ec
This commit is contained in:
Petr Kovar 2017-10-24 20:16:37 +02:00
parent dc4326fa53
commit 3acee39f53
2 changed files with 111 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/doc-contrib-guide/source/index.rst
View File

@ -23,6 +23,7 @@ Contents
quickstart.rst
team-structure.rst
team-vision.rst
non-native-english-speakers.rst
blueprints-and-specs.rst
project-guides

110
doc/doc-contrib-guide/source/team-vision.rst Normal file
View File

@ -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 <https://governance.openstack.org/tc/reference/tags/>`_ 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.