Hi all, Just wanted to share a summary of docs- and i18n-related meetings and discussions we had in Dublin last week during the Rocky Project Teams Gathering.
I think we can say both our teams, docs and i18n, are now pretty stable member-wise, following new processes and goals set up earlier in the Pike cycle. At the PTG, this was reflected in a rather fluctuating attendance of 3 to 12 ppl during the first two days. The meetings related to contributor docs and community onboarding proved to be most popular and caught more attention than others. As with previous PTGs, it is important to note that many of our cores couldn't attend, sadly. Traveling to OpenStack events remains a challenge for many and this was again mentioned during the PTG feedback session. The overall schedule for all our sessions with additional comments can be found here: https://etherpad.openstack.org/p/docs-i18n-ptg-rocky Our team picture from the Croke Park stadium (with quite a few members missing) can be found here (thanks Kendall!): https://pmkovar.fedorapeople.org/ptg/docs-ptg-dublin-2018.jpg To summarize what I found most important: GOVERNANCE DOCS TAGS We used to have the docs:follows-policy governance tag which in fact wasn't implemented by the project teams and we eventually retired it in Pike. Going forward, we want to propose several governance tags for projects to use. Each tag would identify a conformance to a specific area of content management and development, such following common glossary and terminology, tested installation procedures, common content structure, etc. These would serve as signs of maturity of each project. CONTENT REUSE AND CROSS-REFERENCING This is relevant to use cases such as sharing glossary term definitions across project team docs and reusing common content for installation guides across multiple releases. There are several alternatives we can look at further, such as automatically submitting content changes between repos with a bot, using Sphinx extensions (sphinx.ext.intersphinx), etc. More guidance will need to be provided. COMMON ORGANIZATION OF CONTENT Some of the feedback we received from developers at the PTG was centered around offering more guidance in the common organization of content in most popular pages across project team docs. These certainly include landing pages and front pages for each content category (installation, usage, administration, reference, contribution, etc.). SITE ANALYTICS This is related to the previous point in that having access to some of the site analytics data for docs.openstack.org would help the docs project and project teams determine most popular content, content gaps, the keywords users use when searching for content, etc. We discussed this with a number of people from the Foundation. INSTALLATION GUIDE TESTING During the last cycles, there's been little interest from the community in testing installation procedures in an organized high-level manner. For Rocky, we will instead focus on providing more guidance on how to test procedures on an individual level using Gerrit dashboards to track changes, etc. CONTRIBUTOR GUIDE We met with some of the contributor-guide team members to discuss content restructure and reuse, adding more content and cleaning up existing contributor docs, such as the project-team-guide. There's also a First Contact Special Interest Group etherpad that provides more information on the subject of onboarding: https://etherpad.openstack.org/p/FC_SIG_Rocky_PTG TRANSLATIONS Our i18n crew worked on enabling project team docs to be translatable, starting with the openstack-ansible project as a pilot. THAT'S IT? Please add to the list if I missed anything important, particularly for i18n. Thank you to everybody who attended the sessions, and a special thanks goes to all the PTG organizers and the local staff who handled the Beast from the East combined with storm Emma in Dublin in a truly professional manner! Hope to see more of you at the next PTG in Secret Name of Next PTG Location! Cheers, pk __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev