Open Stack

On Thu, Oct 10, 2013 at 12:02 PM, Colin McNamara <colin at 2cups.com> wrote:

> 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.
>


Circling back to take a closer look now that the release is out.

I like your main goal of improving the source documentation. But RST
documentation isn't great source since it can't be xi:included, it gets
hung up in reviews for a long time, it's not well maintained, I'm just not
sure you want to use it as your source. I'm trying to help you avoid a
pitfall here. :)

So far the data shows that the dev docs are less maintained, when we bring
them in to openstack-manuals they tend to improve at a faster rate. I could
go through your review a file at a time and tell you where the info should
go, but I can't make it a priority myself right now. Is there anyone else
you can identify to help you with content placement? I'd also recommend a
file at a time to help reviewers review your patches. Or a project at a
time. Some way of helping reviewers see the whole deliverable will help
reviewers.

Anyone else want to add to the discussion? Feel free to add RST-as-source
to tomorrow's doc team meeting agenda at
https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting#Agenda_for_next_meeting
.

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 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 <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
>
>
>


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