2017/2018 documentation team vision¶
Objective¶
To craft the individual pieces of our vision process into a singular document in order to set goals over the next 12 months.
Note
This document was written from a futuristic perspective.
Background¶
During the Queens PTG, the OpenStack documentation team outlined four critical areas for improvement in our processes. These areas include documenting use cases, setting expectations, improving content visibility, and contributing to documentation.
Looking back over the last year since, we made positive progress in all four areas. Though there is still much work to be done, we have a lot to be proud of!
Use cases¶
In conjunction with the documentation team, the OpenStack Foundation set up a
new Contributor Portal (openstack.org/community), which is a choose your
own adventure for interested user types, such as operators, users, and
contributors. Users select the type of activity they are interested in and are
able to quickly navigate to the appropriate documentation.
In addition, a new set of high-level common use-case documents (for example, how to use Gerrit and how to sign up for a project) are available, which detail step-by-step instructions for common tasks to integrate with the OpenStack community. This resulted in a net increase on the last user survey with regards to the OpenStack documentation and its effectiveness for the community.
The OpenStack documentation team met with a majority of project teams in Secret Name of Next PTG Location to offer assistance and guidelines on developing topic-based documentation with high-level descriptions of OpenStack projects, supported by realistic, cross-community and outcome-specific use cases. Use cases are consistent across projects, following unified information architecture.
Projects first provided a minimum of three defined use cases, then they developed content for the use cases and checked the use cases into their project’s repository. The documentation team measured success by reviewing statistics of the most popular use cases and plans to add additional content to support them during the next cycle.
Setting expectations¶
Over the past year we have seen three positive reviews from the trade press or analyst community on the quality of the OpenStack documentation. Project teams own and maintain their own content and have worked with the i18n team to ensure documents are translatable. Project teams, via their project liaisons, followed the planning process set up by the documentation team to define use cases. Each code commit in the project repository includes documentation, if applicable. We successfully added to the release calendar a window for a set of content reviews with each project liaison, per the project’s needs. Project teams have followed updated Governance documentation tag guidelines when managing their content.
Content visibility¶
Within the last development cycle, the documentation team was able to improve
search engine results through improved search engine optimization (SEO) and
content shaping. The most common search terms, as defined by Google
Analytics, are returning timely and relevant results and correctly pointing
back to the appropriate document on docs.openstack.org.
In an effort to address problems with new and potential users, the
documentation team worked in conjunction with the OpenStack Foundation, the
OpenStack Wiki team, and ask.openstack.org to create consistent messaging
across all of our properties to ensure users are correctly directed to the
new Contributor Portal or the particular project’s documentation on
docs.openstack.org. Over the past year, our success metric has shown a 10%
increase in positive responses from both the COA exam takers and the comments
on the user survey. Additionally, we had increased traffic (> 20%) to
docs.openstack.org, which showed greater utilization by the community.
Finally, a more comprehensive documentation archiving lifecycle was implemented for releases. Archived content is still available to users who need it, but we have added CSS overlays to help avoid confusion and ensure it is clear when legacy content is being viewed. This addressed problems reported by both COA exam takers and operators using older releases that were unable to access older documentation.
Contributing to documentation¶
The documentation team collaborated with the Upstream Institute to help improve mentoring and training aimed specifically at new contributors. A set of training materials was designed by the documentation team to provide guidelines for the Upstream Institute volunteer mentors. Two mentors were chosen to work with the new group of contributors during the OpenStack Summit and PTG, in addition to the onboarding sessions hosted at the Summit. The mentors encouraged the new contributors to utilize their new knowledge of project teams to actively contribute documentation back to the respective project teams.
