openstack-doc-core team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

Hi all -
I wanted to give status updates on some in-flight items since I'm on
vacation for a while and we'll have our next doc team meeting right
after I get back, July 10. So, here goes:

DocImpact flag - The CI team is designing a flag system integrated
into Gerrit that'll work something like this:
1. Developer makes a patch and submits it to one of the OpenStack projects.
2. Developer puts "DocImpact" somewhere in the commit message.
3. A Gerrit hook sends an email with a review.openstack.org link to
the openstack-doc-core@xxxxxxxxxxxxxxxxxxx email.
4. A member of the doc team can click through on the
review.openstack.org link to take a look at the patch and determine
whether to log a Doc Bug (as a task), review the patch if it contains
docs, or some other action.
Any discussion on this new flag implementation?

Deployment Template Blueprint - I've revised this again from F2 (which
is July 5th) to F3 (mid-August) because I'm talking to third-party
editors about including case studies for TryStack or Mediawiki in one
of their upcoming books, licensed Creative Commons. What I've found
though is that TryStack is still working on their Essex upgrade and
I'm not sure if Mediawiki is staying on Diablo. So, this blueprint is
in flight but in a holding pattern. Anyone is welcome to pick up on it
and start writing though. Good way to be a third-party author if
you're interested in such things!

Content Sharing Blueprint - I'm planning with a contract team to
devise a proof-of-concept for
https://blueprints.launchpad.net/openstack-manuals/+spec/design-content-sharing
in the next two-three months. Hopefully we'll have easier content
sharing for API guides by the end of summer.

API Try-it-out Blueprint - On hold, no resources to work on this that I know of.

Metadata on built documents - Looking for status on this from the
clouddocs tool team.

TryStack and api.openstack.org - TryStack will be upgraded to Essex
and when that happens, the api.openstack.org site needs to change to
display v2 for all Compute API calls instead of v1.1. Noting here so
you all know there's a dependency on TryStack for updating
api.openstack.org.

Translations - I've been discussing the design of translations for all
projects and for the documentation itself with Daisy (Ying Chun Guo,
CCed). The Maven plugin,
https://github.com/rackspace/clouddocs-maven-plugin, now supports
building Chinese language PDFs for example. In addition, Daisy has
created a "slicing" tool that creates .pot files that she can upload
to Transifex, the website that OpenStack translators can use to
collaborate on translations. One big audacious idea is to have
separate repositories for each language for documentation. Separate
repos per language would enable native-language reviewers to review
translations - and it would also enable native-language speakers to
write their own documents rather than only translating. I pitch this
idea because I've seen it work well with FLOSS Manuals - such as
fr.flossmanuals.net - where there's a native speaker growing the
community around the docs. It's a way of leaning into the chaos - we
can't ultimately control releases and languages and the amount that's
completed, so maybe we let each language have a level of completion.
Would love thoughts on this.

That's what's up, doc - let me know if you have questions and I'd love
discussion around these items.

Thanks,
Anne