Open Stack

On 3 March 2017 at 00:49, Alexandra Settle <a.settle at outlook.com> wrote:

> Hi team leads,
>
>
>
> I’m sure some of you may or may not have seen, I am currently pushing for
> a ‘documentation review period’ to be officially integrated to the project
> release schedule. You can see the draft verison for pike here:
> https://releases.openstack.org/pike/schedule.html  If anyone has not seen
> my email, you can view here: http://lists.openstack.org/
> pipermail/openstack-dev/2017-March/113144.html So far, we have mostly
> positive responses.
>
>
>
> My reason for bringing this up is because we have unfortunately swept up
> with a lot of bugs post-Ocata release referencing out-of-date content in
> our guides. Several guides are still referencing Newton content, or were
> never updated and are unworkable. These guides include our Installation
> manuals and reference guides.
>
>
>
> From what I can tell, this is a by-product of miscommunication. But I
> would like to improve on this, and ensure it does not happen again in the
> future. Here is a link the overview of our release tasks currently:
> https://docs.openstack.org/contributor-guide/release/taskoverview.html
>
>
>
> I propose we renew what the specialty leads are doing on our side at
> release time (especially with the guides that are on the release schedule),
> and what the cross-project liaisons (CPLs) for docs need to be doing on
> their side as there appears to be a little bit of discord between the two
> currently.
>
>
>
> *Brian and Maria* – as our most recent release managers, how did pinging
> the CPLs go before release? Were they responsive?
>
>
>

I'm not sure about the status of the other guides, but certainly the
Install Guide has proved problematic. I think we should explicitly ask the
CPLs from the projects included in the Install Guide to review their
chapters. If that had happened we wouldn't have missed the Cellsv2 and
Placement content. To be honest, we should have known about those two items
prior to the release process starting. Perhaps we need to ask CPLs early in
the cycle to send us a list of items they have planned for the next release
that they think will require changes to our documentation. We might get
some false positives with work that doesn't make it into the release or
that doesn't actually belong in our books, but I think that is better than
scrambling around after the release trying to fix broken docs.

So maybe a two-pronged approach?

1. Connect with CPLs early in the cycle to find out what they have in the
pipeline that we should keep an eye on. As we get close to release we can
check on those items to see where things are at.
2. Make the review process easier for CPLs by sending them a list of
chapters/sections they should review prior to release. Perhaps tracked on
an etherpad so they can record issues and we can track progress.

Brian


> Team – I want your genuine opinions and suggestions on how we can best
> improve this process outside of making it official. Do we need to have
> liaisons that are better integrated in the documentation team? Perhaps a
> partnership with a doc person?
>
>
>
> As much as I appreciate the argument that, “If $project don’t update their
> docs, it’s their problem.” It all comes down to the user, and if the user
> cannot install $project because it’s not updated, then what do we have?
>
>
>
> Looking forward to your thoughts and opinions,
>
>
>
> Alex
>
>
>
>
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20170309/c8272732/attachment.html>