Open Stack

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. 

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. 


Regards,
Colin

Colin McNamara
People | Process | Technology
--------------------------------------------
Mobile: 	858-208-8105
Twitter:	@colinmcnamara
Linkedin:	www.linkedin.com/colinmcnamara
Blog:	www.colinmcnamara.com
Email:	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> (925) 980-4729
>> 
>> On Oct 9, 2013, at 7:54 PM, Tom Fifield <tom at openstack.org
>> <mailto: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>> 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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20131010/25c6cfc6/attachment-0001.html>