Open Stack

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

*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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20131028/1da38b4f/attachment-0001.html>