Open Stack

Anne and Colin, I'd be happy to help with content management and migration.
-Nermina

On Monday, October 21, 2013, Anne Gentle wrote:

>
>
>
> On Thu, Oct 10, 2013 at 12:02 PM, Colin McNamara <colin at 2cups.com<javascript:_e({}, 'cvml', '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 <javascript:_e({}, 'cvml',
> '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/1d05dff1/attachment.html>