Open Stack

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 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.

>
>     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.

>
>
>     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).
> 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