Open Stack

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