Open Stack

On 29/08/13 07:38, Anne Gentle wrote:
> 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?

This might be too obvious to warrant inclusion, but is it worth having a
separate line about following the conventions/enforcing the conventions
? I do note it's already mentioned in the context of cleanup work *shrug*

> Thanks,
> Anne
> 
> 
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>