Elaborate on the business value of documentation owners
Recent threads on the openstack-discuss mailing list [0] suggest revisiting the idea of formatting the help-wanted list to represent the value each initiative provides a sponsor. This feedback was given to the Technical Committee during the Vancouver summit in 2018. This is an attempt at describing the value well-documented software has on a business. [0] http://lists.openstack.org/pipermail/openstack-discuss/2019-January/002252.html Change-Id: Id12e50f084025713fc3aefc9c9ddf50b3a9072db
This commit is contained in:
parent
587055d021
commit
d7f99e14e9
|
@ -25,29 +25,69 @@ out to the TC sponsor, or the PTL of the affected project.
|
|||
1. Documentation owners
|
||||
=======================
|
||||
|
||||
The #1 pain point in OpenStack, especially for new potential adopters, is
|
||||
complexity. While cutting down complexity everwhere we can is critical,
|
||||
Description
|
||||
-----------
|
||||
|
||||
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.
|
||||
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. An
|
||||
ambitious `plan`_ to further decentralize the Documentation team (and turn it
|
||||
into a guidance and mentoring support team) has been outlined. To be
|
||||
successful, this plan requires project teams to own their own documentation,
|
||||
which means that the role of documentation owners will be critical.
|
||||
dawn of OpenStack, despite the heroic efforts of previous team members. The
|
||||
community outlined an ambitious `plan`_ to decentralize the Documentation team,
|
||||
turning it into a guidance and mentoring support team. To be successful,
|
||||
project teams need to own their documentation, which means that the role of
|
||||
documentation owners will be critical.
|
||||
|
||||
Volunteers for this role will in the short term drive this ambitious
|
||||
transition, by being members of their project team and members of the new
|
||||
decentralized documentation team. On the long-term they will become a
|
||||
reference go-to person in their project, and respected mentors in the
|
||||
OpenStack community.
|
||||
Volunteers for this role will drive this ambitious transition, by being members
|
||||
of their project team and members of the new decentralized documentation team.
|
||||
On the long-term, they will become a reference go-to person in their project,
|
||||
and respected mentors in the OpenStack community.
|
||||
|
||||
Interested? Contact the Documentation PTL (pkovar) or the TC sponsor for
|
||||
this item (dhellmann).
|
||||
Value
|
||||
-----
|
||||
|
||||
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/
|
||||
.. _`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
|
||||
=====================================
|
||||
|
|
Loading…
Reference in New Issue