Open Stack

Love these questions! Some thoughts interspersed below.


On Wed, Oct 30, 2013 at 10:02 PM, Lana Brindley
<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 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.

Recognizing bugs: Disqus comments, 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.




> 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.
Thanks for asking - great questions. Let's LEVEL UP.
Anne


> Thanks,

Lana
> --
> Lana Brindley
> Technical Writer
> Rackspace Cloud Builders Australia
> http://lanabrindley.com
>
> ______________________________**_________________
> Openstack-docs mailing list
> Openstack-docs at lists.**openstack.org <Openstack-docs at lists.openstack.org>
> http://lists.openstack.org/**cgi-bin/mailman/listinfo/**openstack-docs<http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs>
>



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