====================
Documentation owners
====================

Summary
-------

The OpenStack community is seeking individuals with an interest and
passion for documentation to help drive user, operator, and developer
focused documentation from within each of the OpenStack project teams.
This is in accordance with the end goal of a fully decentralized
documentation team.

Business Case
-------------

Volunteers for this visible role will form part of an expert liaison group
focused primarily on the success of OpenStack documentation. They will become
a reference go-to person in their project, and respected mentors in the
OpenStack community.

OpenStack distributions and vendors who have their own downstream
documentation can place their contributors upstream in
projects. Upstream documentation can later be used as a source for
downstream documentation knowing that it has been reviewed by the full
cadre of upstream experts in the relevant project at feature
development time. Leveraging the larger upstream pool of project
experts will improve documentation quality while reducing time and
cost of downstream documentation production.

Technical Details
-----------------

The #1 pain point in OpenStack, for contributors and users alike, is
complexity. While cutting down complexity everywhere we can is critical,
proper documentation is essential in addressing that complexity. It directly
benefits operators and users of OpenStack, but also facilitates ramping up new
direct contributors to the project itself.

The documentation team has been struggling with limited resources since the
dawn of OpenStack, despite the heroic efforts of previous team members. The
community outlined an ambitious `plan`_ to dissolve the documentation team as
an official project team and turn it into a guidance and mentoring support
team in the form of a Special Interest Group (SIG).
To be successful, as project teams already own their documentation, a
documentation liaison role will be critical to ensure the documentation
quality is upheld.

Increased Operational Efficiency
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Documentation naturally disseminates knowledge, but it should also be easy for
readers to find what they are looking for. This process reduces bottlenecks on
human resources and support by allowing users, operators, and contributors to
find answers to questions themselves. Less time spent answering common
questions means more time focusing on more complicated requests, maintenance,
and code.

Faster Onboarding
~~~~~~~~~~~~~~~~~

Contributors come from all different backgrounds and experiences. As a result,
they often share similar questions about high-level concepts or processes used
within the OpenStack community or components. Consistently documenting
processes enables contributors without requiring them to pull tribal knowledge
from an existing developer. This documentation fast-tracks contributors to
making productive contributions.

Consistency
~~~~~~~~~~~

Users, customers, and operators are required to reference a vast pool of
documentation spread across multiple repositories and sites. Implementing
consistency in wording, format, content, and location provides readers with a
first-class experience. Additionally, users build confidence and trust in
software when it is well documented.

Contact
-------

To help or inquire about this investment opportunity, reach out to the
OpenStack Discuss mailing `list`_ using the ``[docs]`` tag in the
subject line.  You may also contact the `Documentation`_ PTL or engage
Technical Committee via IRC (``#openstack-tc`` on `OFTC
<https://www.oftc.net/>`_).

.. _`plan`: https://review.opendev.org/#/c/657142/
.. _`list`: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss
.. _`Documentation`: https://governance.openstack.org/tc/reference/projects/documentation.html



