Open Stack

All:

For the RST conversion, are you also going to be targeting the
python-*client documentation that currently exists (e.g.,
python-novaclient, python-swiftclient, ...)?

Lorin


On Tue, Oct 29, 2013 at 5:22 PM, Anne Gentle
<annegentle at justwriteclick.com>wrote:

> Hi again everyone,
>
> Nermina, Sean and I spoke today and Sean's going to modify his blueprint
> and start with a patch that contains the conversion tool plus just the RST
> files for cinder, to be placed in doc/training-guide. He'll show the
> placement in the associates guide so reviewers can see the end-goal as well
> as the steps prior to the training guide update. Nermina can take a look at
> what could be incorporated into other guides.
>
> I hope this is a good step forward to get some proof of concept content in
> there so reviewers can take a look and offer suggestions.
>
> Thanks,
> Anne
>
>
> 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.)
>>
>> *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
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>


-- 
Lorin Hochstein
Lead Architect - Cloud Services
Nimbis Services, Inc.
www.nimbisservices.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20131029/ece15726/attachment.html>