Open Stack

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