Open Stack

On Thu, Oct 10, 2013 at 11:06 AM, Colin McNamara <colin at 2cups.com> wrote:

> Tom (And list). What we have been finding is that the Dev Docs are a rich
> source for conceptual discussions of components to be installed. A specific
> example is the messaging service used in Nova. In the Associate guide,
> there is an installation task of installing and configuring RabbitMQ.
>  Directly before that configuration task there is a conceptual task of
> understanding (at a high level) the messaging architecture, and the
> components that enable its operation.
>
> The RPC section of the Nova developer documentation (found here -
> http://docs.openstack.org/developer/nova/devref/rpc.html)  has a very
> detailed deep dive into this topic. I believe the first section "AMQP and
> Nova" is appropriate to integrate as the conceptual item for this
> installation task. In more advanced courses, subsequent sections such as
> "Broker Load" and "RabbitMQ Gotchas" will be appropriate to include.
>

These sound like the types of info that both Python devs and
deployers/admins/architects would benefit from. Thierry has often noted
this difficulty, how to share that info with both audiences. Here's what
we've done based on the participation and maintenance data we see.

For the Filter conceptual info, we brought it directly into
openstack-manuals, and maintain it there. I think the same could happen
with AMQP. Realize the AMQP page you reference is over a year old. The
Filter page in nova was updated 2 months ago. The one in openstack-manuals
was updated 10 days ago.

I think you need to put the info where it'll be updated more often, and
time and time again, that's in openstack-manuals.

I had hoped that was your role here, to identify what's missing in the
manuals and add it. I think you're identifying it, all we're asking is that
you bring it in where needed, not in an automated way, but in a
maintainable trackable way.

Or, do a proof of concept where specific conceptual content builds on
Jenkins and integrates with the openstack-manuals. Or, wait for Todd
Morey's proof of concept with mixed-type content.


>
> I'd like to also address the subject of improving manuals content within
> training-manuals by copying vs including external sources. Improving the
> training-manuals content is an important goal. I however have been a bit of
> a stickler within Training-Guides on content duplication. I personally
> don't believe that it is sustainable to maintain two completely separate
> sources of documentation in a six month release cycle with major changes in
> structure each release while maintaining forward progress on the advanced
> courses. I however may be completely off base on this belief and welcome
> comments and external perspective.
>
> With that being said, in a perfect wold the Developer Docs would all be in
> XML that could be included into openstack-manuals content natively. The
> world we live in has developer content written in ReStructured Text, which
> is extremely easy for people to update and I doubt will change (or should
> be changed). The next best thing for me would be for Jenkins to create
> docbooks XML content on build, or a similar XML content that could be
> easily included at a granular level into the larger  documentation base.
>

Conceptual information is welcomed in openstack-manuals, and like I note
above, the pattern we see is that the dev docs are not well-maintained. My
vision is that docbook becomes more invisible but we need tooling for that.
Thanks Colin and Sean for bringing up what you find as you go!
Anne


>
>
> Regards,
>
> Colin
> *Colin McNamara*
> People | Process | Technology
> --------------------------------------------
> *Mobile*:  858-208-8105
> *Twitter: *@colinmcnamara <http://www.twitter.com/colinmcnamara>
> *Linkedin*: www. <http://www.linkedin.com/colinmcnamara>
> linkedin.com/colinmcnamara <http://www.linkedin.com/colinmcnamara>
> *Blog*: www.colinmcnamara.com
> *Email*: colin at 2cups.com <//colin at 2cups.com>
>
>
>
>
>
>
> On Oct 9, 2013, at 9:02 PM, Tom Fifield <tom at openstack.org> wrote:
>
> Oh?
>
> Can you point out some of the good sections for associates in the devref
> you're looking at? We should also work on improving the manuals for you if
> there's stuff missing. In theory the devref is only for dev stuff, which is
> why I was asking - I didn't think you were up to writing the developer
> training yet :D
>
> Regards,
>
>
> Tom
>
> On 10/10/13 15:00, Sean Roberts wrote:
>
> Good question. The immediate need is for the associate guide that we are
> working on right now.
>
>
> Sean Roberts
> Infrastructure Strategy
> seanrob at yahoo-inc.com <mailto:seanrob at yahoo-inc.com<seanrob at yahoo-inc.com>>
> (925) 980-4729
>
> On Oct 9, 2013, at 7:54 PM, Tom Fifield <tom at openstack.org
> <mailto:tom at openstack.org <tom at openstack.org>>>
>  wrote:
>
> Hi Sean,
>
> Just wondering - is this mainly for the "Developer Training Guide" ?
>
> Regards,
>
>
> Tom
>
> On 10/10/13 11:48, Sean Roberts wrote:
>
> Sounds great. I'll post my latest code to my repo and share.
>
> ~sean
>
> On Oct 9, 2013, at 17:00, "David Cramer" <david.cramer at rackspace.com
> <mailto:david.cramer at rackspace.com <david.cramer at rackspace.com>>> wrote:
>
> Hi Sean,
> xslt would be well-suited to cleaning up the output of pandoc and
> converting it to DocBook 5.x. This could be invoked from your python
> script:
>
>
> https://svn.code.sf.net/p/docbook/code/trunk/docbook/relaxng/tools/db4-upgrade.xsl
>
> If you have other cleanup to perform, we could add the necessary logic
> to the db4-upgrade.xsl.
>
> I'll be happy to help with the xslt and I think the result would be more
> robust.
>
> Regards,
> David
>
> On 10/09/2013 06:37 PM, Sean Roberts wrote:
> The training-manuals team is proposing a blueprint to implement rst to
> xml conversion script. This code is used to convert devref project rst
> documentation into xml that the openstack manuals project can use. The
> Training-manuals sub-project will use xi:include statements so the
> converted xml becomes part of the training guides during build. The
> conversion script will live in the ./training-guide/sources sub
> directory of the training-manuals sub-project. The converted xml gets
> placed within ./training-guide/sources/<project> directories. The
> conversion script will be run at the same time as when the
> openstack-manuals repo updates are pulled. This will allow the training
> manuals team to find xml content and include it with the training
> guides. If the source RST has a bug, then the RST source will be
> patched, and the XML will get the bug fix through the next run of the
> conversion script.
>
> Blueprint
> here
> https://blueprints.launchpad.net/openstack-manuals/+spec/rst-xml-conversion
> Wiki details
> here
>
> https://wiki.openstack.org/wiki/Training-manuals#RST-XML_Conversion_automation
>
> Sean Roberts
> Infrastructure Strategy
> seanrob at yahoo-inc.com <mailto:seanrob at yahoo-inc.com> (925) 980-4729
>
>
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> <mailto:Openstack-docs at lists.openstack.org>
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> <mailto:Openstack-docs at lists.openstack.org>
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
>
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>


-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20131010/3a87a752/attachment.html>