93 lines
3.8 KiB
ReStructuredText
93 lines
3.8 KiB
ReStructuredText
====================
|
|
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
|
|
|
|
|
|
|