Open Stack

All,

I've been drafting this for the wiki this week, and wanted to ensure I'm
capturing our current thinking on review guidelines and processes for
documentation. A few questions have come up recently that I hope these
guidelines address. Let me know your thoughts.


=== Reviewer Guidelines ===

We do not currently require a bug to be linked from every doc patch
submission in order to consider it for review. While many OpenStack
projects associate every commit to either a bug ID or blueprint name,
documentation does not have this strict requirement due to the balancing
act between disciplined doc work and ensuring that too much process doesn't
get in the way of making docs fixes quickly.

While generally we do want doc bugs for feature work, as a team we haven't
been super strict about a bug for each patch. That said, we do have this
ongoing bug: https://bugs.launchpad.net/openstack-manuals/+bug/1121866 for
cleanup to match the OpenStack Conventions documented at
https://wiki.openstack.org/wiki/Documentation/Conventions. We also have
https://bugs.launchpad.net/openstack-manuals/+bug/1217503 for ongoing
markup changes to match our conventions. These bugs can be used for cleanup
work related to conventions.

We have to make a judgement call about super-fine-grained inclusions (where
you xi:include content below a <section> or <chapter> level. Sometimes
reuse is not the best solution and rewriting the content would be better.
Sometimes reuse is the right solution and you should rewrite something
generically for re-use in multiple places. With many contributors looking
at the repo for the first time, it's a fine line to walk, so reviewers need
to ensure we use good judgement on reuse thinking of ongoing maintenance.

------------------

Any other guidelines to capture?
Thanks,
Anne
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130828/81d3c503/attachment.html>