diff --git a/reference/help-most-needed.rst b/reference/help-most-needed.rst index 8ff269a84..5fc74d580 100644 --- a/reference/help-most-needed.rst +++ b/reference/help-most-needed.rst @@ -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 =====================================