<div dir="ltr">Love these questions! Some thoughts interspersed below.<div class="gmail_extra"><br><br><div class="gmail_quote">On Wed, Oct 30, 2013 at 10:02 PM, Lana Brindley <span dir="ltr"><<a href="mailto:openstack@lanabrindley.com" target="_blank">openstack@lanabrindley.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">Hi everyone,<br>
<br>
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.<br>
<br>
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?)<br>
<br></blockquote><div><br></div><div>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.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
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. </blockquote>
<div><br></div><div>Whee you can really bring us up a level with queries like these! Wahoo. </div><div><br></div><div>Recognizing bugs: Disqus comments, <a href="http://ask.openstack.org">ask.openstack.org</a> 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.</div>
<div>Opening bugs: Launchpad bugs in either openstack-manuals or openstack-api-site or the repo where the doc's source content lives. </div><div>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.</div>
<div>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. </div><div>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.</div>
<div>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.</div>
<div><br></div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">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?<br>
<br></blockquote><div><br></div><div>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 <a href="https://wiki.openstack.org/wiki/Documentation/ProjectDocLeads">https://wiki.openstack.org/wiki/Documentation/ProjectDocLeads</a>). Project-by-project we can improve on the communication lines and expert identification. </div>
<div>Thanks for asking - great questions. Let's LEVEL UP.</div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
Thanks, </blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
Lana<span class=""><font color="#888888"><br>
-- <br>
Lana Brindley<br>
Technical Writer<br>
Rackspace Cloud Builders Australia<br>
<a href="http://lanabrindley.com" target="_blank">http://lanabrindley.com</a><br>
<br>
______________________________<u></u>_________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org" target="_blank">Openstack-docs@lists.<u></u>openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/<u></u>cgi-bin/mailman/listinfo/<u></u>openstack-docs</a><br>
</font></span></blockquote></div><br><br clear="all"><div><br></div>-- <br>Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>
</div></div>