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).