Open Stack

Anne, I agree with you on that. I've asked Sean that question and his
response was that they need to keep maintaining the RST files until they're
ready to switch to XML. Whether they can just begin working with the xml
now is a question Sean and Colin need to answer. Making that choice and
dealing with it now rather than later would make the docs work easier but
I'm not sure how exactly it impacts their workflow. Thanks! - Nermina


On Tue, Oct 29, 2013 at 10:10 AM, Anne Gentle <annegentle at justwriteclick.com
> wrote:

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



-- 
Thank you!

Nermina Miller
Tech Writer and Editor
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20131029/3af01a0c/attachment-0001.html>