Open Stack

Sean my sense is that this is time sensitive for you. Can you give me a
call please?

Anne


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

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



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