Open Stack

I absolutely believe that the appropriate role is to improve the source documentation. Right now I'm just riding a find line between improving and duplicating. My focus has been on getting the structure of training-guides through included content, and then when we get to our alpha to focus on improving the referenced content. 

A direct example of that would on the administrative section that references the user-guide content. There are items in there that could benefit from visual representation of the steps noted. My goal is to get the included content roughed out in the training-guide, and then engage the user group contributors that we have been building to do things like create visual representations of configuration steps that are unclear. 

So, to be very clear. My goals are to improve the source documentation. My suggested method is to focus on xi:inclusion as much as possible within training-guides. This drives the improvement in content to the sources that are referenced, vs creating yet another external operations guide that won't be able to map to the six month release schedule.
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 10, 2013, at 9:35 AM, Anne Gentle <annegentle at justwriteclick.com> wrote:

> 
> 
> 
> 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
> 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
> 
> 
> _______________________________________________
> 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/10e5d5cb/attachment-0001.html>