Open Stack

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