openstack
/
governance
Code Issues Proposed changes

Merge "Elaborate on the business value of documentation owners"

This commit is contained in:
Zuul 2019-04-18 19:55:33 +00:00 committed by Gerrit Code Review
parent 81597180ec d7f99e14e9
commit 9529d4a45f
1 changed files with 56 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
reference/help-most-needed.rst
View File

@ -49,29 +49,69 @@ for connecting with the right group of people to get resources up-to-speed.
1. Documentation owners 1. Documentation owners
======================= =======================
The #1 pain point in OpenStack, especially for new potential adopters, is Description
complexity. While cutting down complexity everwhere we can is critical, -----------
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 proper documentation is essential in addressing that complexity. It directly
benefits operators and users of OpenStack, but also facilitates ramping up benefits operators and users of OpenStack, but also facilitates ramping up new
new direct contributors to the project itself. direct contributors to the project itself.
The documentation team has been struggling with limited resources since the The documentation team has been struggling with limited resources since the
dawn of OpenStack, despite the heroic efforts of previous team members. An dawn of OpenStack, despite the heroic efforts of previous team members. The
ambitious `plan`_ to further decentralize the Documentation team (and turn it community outlined an ambitious `plan`_ to decentralize the Documentation team,
into a guidance and mentoring support team) has been outlined. To be turning it into a guidance and mentoring support team. To be successful,
successful, this plan requires project teams to own their own documentation, project teams need to own their documentation, which means that the role of
which means that the role of documentation owners will be critical. documentation owners will be critical.
Volunteers for this role will in the short term drive this ambitious Volunteers for this role will drive this ambitious transition, by being members
transition, by being members of their project team and members of the new of their project team and members of the new decentralized documentation team.
decentralized documentation team. On the long-term they will become a On the long-term, they will become a reference go-to person in their project,
reference go-to person in their project, and respected mentors in the and respected mentors in the OpenStack community.
OpenStack community.
Interested? Contact the Documentation PTL (pkovar) or the TC sponsor for Value
this item (dhellmann). -----
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
-------
For questions about getting involved with this initiative, reach out to the
OpenStack Discuss mailing `list`_. You may also contact the `Documentation`_
PTL or the Technical Committee sponsor for this item (dhellmann).
.. _`plan`: https://review.openstack.org/#/c/472275/ .. _`plan`: https://review.openstack.org/#/c/472275/
.. _`list`: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss
.. _`Documentation`: https://governance.openstack.org/tc/reference/projects/documentation.html
2. Community Infrastructure Sysadmins 2. Community Infrastructure Sysadmins
===================================== =====================================