113 lines
5.2 KiB
ReStructuredText
113 lines
5.2 KiB
ReStructuredText
.. _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``. Over the past year, our success metric has shown 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.
|
|
|
|
.. _archiving lifecycle: http://specs.openstack.org/openstack/docs-specs/specs/queens/retention-policy.html
|
|
|
|
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.
|