Open Stack

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20131021/179f1480/attachment.html>