Open Stack

Hi Matt, sorry this dropped off my radar but this is a great discussion to
have. More below.


On Mon, Mar 10, 2014 at 9:47 PM, Matt Kassawara <mkassawara at gmail.com>wrote:

> I'm wondering if the training guide maintainers could collaborate more
> with maintainers of other documents to reduce the amount of duplicate
> effort and increase parity. For example, the training guide labs could more
> easily reference newer releases of OpenStack and provide a smoother
> transition to the manual installation process by following the installation
> guide. Just throwing the idea out there...
>


Sean and Colin, you have been the leaders for the community training
efforts, and I'd like to get your input.

We have been incubating the training guides in the Documentation Program.
It would be great to walk through some of the ways the training group could
graduate, and one of the questions we keep having is about scope and
strategically leveraging docs efforts. What's your sense of these scope
questions related to where the training manuals are currently?

** Project must have a clear and defined scope.

** Project's scope should represent a measured progression for OpenStack as a
   whole.
** Project should not inadvertently duplicate functionality present in other
   OpenStack projects. If they do, they should have a clear plan and timeframe
   to prevent long-term scope duplication.

** Project should leverage existing functionality in other OpenStack projects
   as much as possible


Duplication and correct/strategic leverage is a concern for me - reviewing
updates to the training manuals when the information is also duplicated
elsewhere makes for double the work for the docs core reviewers. Examples:
- Vagrant or VM install instructions rather than leveraging and improving
the community install guide or ensuring DevStack is working well (and
DevStack is not in the scope of personas for openstack-manuals).
- How to contribute to OpenStack docs maintained in the openstack-manuals
repo itself, rather than one-source-of-truth in the wiki
- Apparent imports of documentation from other places, such as
http://docs.openstack.org/developer/nova/devref/rpc.html going into
https://review.openstack.org/#/c/80486/5/doc/training-guides/module001-ch008-queues-messaging.xml
--
this is problematic because it wasn't written based on the Conventions in
the first place, and may or may not be something we should clean up and put
into the Cloud Admin Guide. By having the training manuals take that but
not improve it or find a better integration point, we have added to
technical debt rather than improving the docs. Another recent example is
https://review.openstack.org/#/c/80503/3 where Shilla spent time on a patch
before realizing that the file wasn't being used anywhere, and Andreas
spent time reviewing before realizing it wasn't being used.
- We still have an audience concern, with the developer training manual not
matching any persona in the openstack-manuals repo.
- When the training-guides folder gets updated and pushed, not waiting for
+2 from two cores, this caused problems in the past. I think they're
resolved now, but I would prefer that the training team can eventually have
their own core team, reviewers, and repository. How close are we to meeting
that goal of graduation and a separate, diverse team?

I'd love to start the conversation here but let's also plan to continue it
in team meetings and at the summit.

Thanks,
Anne



>
> _______________________________________________
> 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/20140326/1ddcd89e/attachment.html>