Open Stack

On Thu, Oct 31, 2013 at 1:05 AM, Lana Brindley
<openstack at lanabrindley.com>wrote:

> On 31/10/13 13:50, Anne Gentle wrote:
>
>> Love these questions! Some thoughts interspersed below.
>>
>>
> Thanks so much for the fast and detailed reply. I'm going to need some
> time to digest this in the large part, but I've added in a few comments
> inline to keep the conversation rolling.
>
>
>> On Wed, Oct 30, 2013 at 10:02 PM, Lana Brindley
>> <openstack at lanabrindley.com <mailto:openstack@**lanabrindley.com<openstack at lanabrindley.com>>>
>> wrote:
>>
>>     Hi everyone,
>>
>>     As you know, I'm new to Rackspace and Openstack docs. Therefore,
>>     some of my questions might have really simple answers but I just
>>     haven't discovered them yet (please feel free to enlighten me!).
>>     However, based on advice from Tom, there are some larger questions
>>     here that would bear discussion.
>>
>>     I would like to be doing more docs reviews generally, but I'm kind
>>     of stuck on knowing what's expected of reviewers. What, in your
>>     mind, is considered a successful patch? Is it just grammar and
>>     spelling, or is it sucessfully conveying the message (generally good
>>     writing), or is it technical accuracy (and if so, to what extent?
>>     Should I be individually testing each command? Researching concepts?)
>>
>>
>> To me it's technical accuracy above all including testing each command.
>> if you can't test commands, find a reviewer who can. Then also spelling
>> and grammar do count, though I'm always balancing "is it better than we
>> have now" with "craptastic writing, gee" -- so yes it's a judgment call
>> on whether to value technical over "good." I also tend to patch patches
>> where it's likely the author won't have time/ability to finesse for
>> better writing. Michael asked good questions about English-as-a-second
>> language developers at the docs boot camp.
>>
>
> This is really helpful, thank you. Is this documented anywhere? I think it
> would be good to point new contributors to. Happy to help put it together
> if nothing exists yet.
>
>
Please enhance
https://wiki.openstack.org/wiki/Documentation/HowTo#Reviewing_Documentationas
you see fit.

Even 2 years ago I asked small teams like the infra team how they handled
reviews, and since they were just 2 people at the time their guidelines
were very much speed-oriented. They asked questions like, is it better than
what we have now, does it work, and so on. So since the team was so very
small (even in grizzly 3 of us wrote half the doc patches) speed was valued
over quality. Now that we are growing these guidelines can value quality
over speed, especially at this time of the release. But as the release
nears you'll find we need to ever-so-slightly increase our patching and
that is when we'll need to increase review pushes (safely of course). If
you can encapsulate that for newcomers feel free.


>
>
>>     This has lead to some larger questions around process. While the
>>     toolchain is really robust (and impressive, I must say!), what is
>>     the process around recognising and opening bugs, triaging them and
>>     assigning them to writers, researching and writing content, and
>>     ennsuring that content is correct.
>>
>>
>> Whee you can really bring us up a level with queries like these! Wahoo.
>>
>
> Heh, I'm all about process, me ;)
>
>
>> Recognizing bugs: Disqus comments, ask.openstack.org
>> <http://ask.openstack.org> questions, questions on IRC, these areas
>>
>> help. I have asked the QA team if they were interested in doc quality
>> control and they're mostly just interested in API doc bugs. More on that
>> later.
>> Opening bugs: Launchpad bugs in either openstack-manuals or
>> openstack-api-site or the repo where the doc's source content lives.
>> Triaging bugs: Tom is our best triager, Andreas as well, and at boot
>> camp I asked new contributors to get good at this. Triaging is hardest
>> due to the difficulty in knowing the right answer or getting the right
>> answer.
>> Assigning: Mostly I ask people before assigning them, and most people
>> assign themselves. We ask in comments if someone holds a bug for a while
>> if they'll get to it or release it.
>> Researching and writing: highly difficult to know and learn what you
>> need, you need access to people doing what you need to doc. You're well
>> placed for that access.
>> Ensuring content is correct: comes back to the review process, we can
>> help you find technical reviewers. I bug people on IRC and with email
>> all the time. Our system also lets you notify a reviewer by adding them
>> to the list. Again you're well placed to nag people productively.
>>
>
> This is all awesome info, thank you. Again, is this documented somewhere?
> I think I would like to spend more digesting this to work out how I can
> best contribute here.


Every process we have should be on the wiki, so add to pages where you
don't find this type of info.

Thanks!

Anne


>
>
>
>>
>>     Is there any capacity for QA aside from code review (which is
>>     largely done by other writers, from what I can see)? Do you, at any
>>     point, expect developers to review docs patches relevant to their
>>     area of expertise? How do you identify and communicate with subject
>>     matter experts, and what input do they have to the docs process?
>>
>>
>> Another yippee from me. We can get better at this - add devs to reviews,
>> bug them constantly, identify doc leads to help review and triage bugs
>> project-by-project (see
>> https://wiki.openstack.org/**wiki/Documentation/**ProjectDocLeads<https://wiki.openstack.org/wiki/Documentation/ProjectDocLeads>
>> ).
>> Project-by-project we can improve on the communication lines and expert
>> identification.
>>
>
> I think there is a lot of scope here for us to create, if not new
> processes, than at least some increased expectations for best practice.
> It's interesting (but certainly not surprising) that QA haven't expressed a
> desire to help. I've got a few ideas here, but need to be able to cogitate
> more to be able to articulate them effectively. Watch this space.
>
>
>  Thanks for asking - great questions. Let's LEVEL UP.
>>
>
> Awesome, thanks for being so receptive!
>
> Looking forward to working on this :)
>
>
> Lana
>
> --
> Lana Brindley
> Technical Writer
> Rackspace Cloud Builders Australia
> http://lanabrindley.com
>



-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20131031/bc947c6e/attachment-0001.html>