Open Stack

On Tue, Oct 29, 2013 at 8:46 AM, Nermina Miller <nerminamiller at gmail.com>wrote:

> Hi, Anne! The audience for each specific guide are the roles supported by
> OpenStack certification programs. That sounds pretty typical for training
> guides. As far as technical debt, this process wouldn't differ too much
> from what we did with the other guides leading up to Havana release. One
> limitation in this particular case is this pesky fact that RST files have
> to be edited natively.
>

I think this point is the disconnect we have. Here's my vision:
If an RST file has relevant info for a training manual, convert it
permanently to XML and incorporate it into an existing manual.
Then, the training manual points to the file in openstack-manuals.

This has been done in the past over and over. What's the need for
maintaining RST?

Anne


> But, the training group wants to transition to xml, and so we should help
> them with tools like Oxygen licenses. And then, anyone would be able to
> edit them. Keep in mind that only these devref files would not be editable
> at first. We would be able to edit the training books themselves. And we
> would be able to give them comments on the other files. We need to help
> them get started. They crave community feedback. Can the guides be released
> as work in progress? Thank you for such a great dialog! - Nermina
>
>
> On Mon, Oct 28, 2013 at 9:51 PM, Anne Gentle <
> annegentle at justwriteclick.com> wrote:
>
>>
>>
>>
>> On Mon, Oct 28, 2013 at 7:45 PM, Nermina Miller <nerminamiller at gmail.com>wrote:
>>
>>> Hello everyone,
>>>
>>> I've reviewed the training docs and spoke to Sean today, and here is a
>>> proposed solution for inclusion of the devref files converted from rst:
>>>
>>> *Immediate Steps/First Patch*
>>> - Submit the Associates Guide with xi:inclusions of the 30 relevant
>>> devref files (and appropriate updated xi:includes from the other guides)
>>> - Add the entire batch of the devref files to the Common folder
>>> (subfolder Training) so the files can be made available to the other guides
>>> in the long term. (Why all? Because the py script updates and converts them
>>> ALL at the same time. You may already know this but it helps to explain the
>>> need for such a large batch.)
>>>
>>
>> The large batch was our hard stop as a group. Tom named translation as a
>> concern. I have a concern with need based on audience and taking on
>> technical debt (you mention editing below, hence my concern) by having
>> those in the repo at all. Have you found a determination of what files can
>> be incorporated into the other manuals? What content is actually missing?
>> There has to be a better way to bring missing content into the
>> openstack-manuals repository that doesn't involve a merge-then-edit process.
>>
>> Thanks,
>> Anne
>>
>>
>>>
>>> *NOTE:* Andreas, Sean may ask you for help to figure out the best
>>> commit procedure considering that the training guides may need to be made
>>> available for other releases besides Havana. (I've shared the latest
>>> backporting steps with Sean.)
>>>
>>> *IMPORTANT:* Hold off on the editing of rst converts until Sean's team
>>> publishes an appropriate procedure for that. All of the devref xml files
>>> have to be edited in the native rst format and then automatically converted
>>> with the script that will be stored in Common. Once the guide is merged,
>>> you can begin making comments and editing the files using the said
>>> procedure. (Sean said he would add it to the How To wiki.) Understand that
>>> this is a work in progress that needs the community's feedback through bug
>>> logs and fixes. That also means it would be incredibly helpful to add the
>>> training guides to the OpenStack docs index along with Disqus and Launchpad
>>> links.
>>>
>>> *Further Steps*
>>> - Add each of the remaining training guides with the appropriate
>>> xi:includes to the devref files in Common
>>> - Transition to the xml format so a wider audience can edit the files
>>> and for easier updates (and to eliminate the need for conversion). Also,
>>> align those docs with the OpenStack docs file naming and other conventions.
>>>
>>> Sean is planning to submit the first patch tomorrow. It would be great
>>> to have at least one guide to showcase in Hong Kong, and I believe we need
>>> to help Sean make that happen so the training group can begin receiving
>>> feedback and growing their guides live.
>>>
>>> Thank you, Sean! Please correct or add to any of the information listed
>>> here. And, thank you, all for considering these points.
>>>
>>> Nermina
>>>
>>>
>>> On Mon, Oct 21, 2013 at 8:52 PM, Nermina Miller <nerminamiller at gmail.com
>>> > wrote:
>>>
>>>> No problem, Anne. Colin, if this is the missing batch, where is the
>>>> rest of the guide? Also, do you have a blueprint or a proposed ToC I can
>>>> take a look at? Please brief me on the history of training docs a little.
>>>> Thanks much! - Nermina
>>>>
>>>>
>>>> On Mon, Oct 21, 2013 at 7:52 PM, Anne Gentle <
>>>> annegentle at justwriteclick.com> wrote:
>>>>
>>>>>
>>>>>
>>>>>
>>>>> On Mon, Oct 21, 2013 at 6:43 PM, Nermina Miller <
>>>>> nerminamiller at gmail.com> wrote:
>>>>>
>>>>>> Anne and Colin, I'd be happy to help with content management and
>>>>>> migration. -Nermina
>>>>>>
>>>>>>
>>>>> Awesome, Nermina! I think you'll find a list of content they found
>>>>> missing at
>>>>> https://review.openstack.org/#/c/50509/1
>>>>>
>>>>> And someone do tell me if I'm being crazy in taking on more conceptual
>>>>> doc that we might not be able to maintain. I trust you all!
>>>>>
>>>>> Thanks,
>>>>>
>>>>> Anne
>>>>>
>>>>>
>>>>>> On Monday, October 21, 2013, Anne Gentle wrote:
>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> 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
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> 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 <
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> --
>>>>>>> Anne Gentle
>>>>>>> annegentle at justwriteclick.com
>>>>>>>
>>>>>>
>>>>>>
>>>>>> --
>>>>>> Thank you!
>>>>>>
>>>>>> Nermina Miller
>>>>>> Tech Writer and Editor
>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> Anne Gentle
>>>>> annegentle at justwriteclick.com
>>>>>
>>>>
>>>>
>>>>
>>>> --
>>>> Thank you!
>>>>
>>>> Nermina Miller
>>>> Tech Writer and Editor
>>>>
>>>
>>>
>>>
>>> --
>>> Thank you!
>>>
>>> Nermina Miller
>>> Tech Writer and Editor
>>>
>>
>>
>>
>> --
>> Anne Gentle
>> annegentle at justwriteclick.com
>>
>
>
>
> --
> Thank you!
>
> Nermina Miller
> Tech Writer and Editor
>



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