[openstack-tc] Governance documents

Anne Gentle anne at openstack.org
Tue Dec 17 21:29:34 UTC 2013


I want to discuss the needs for publishing governance documents. I think
our requirements start as:
- need for a place for review and vote tracking on governance documents

which this moved some of our documents (reference and resolutions) out of
the wiki and into files in an openstack/governance repository.

The requirements for reading those documents seems to be changing, as Sean
and others are noting that reading these documents on github.com or
git.openstack.org is dissatisfying. So
https://review.openstack.org/#/c/61380/ is how Sean is addressing the
readability concerns I think.

I think that we need to look at the requirements beyond just reading and
into these areas, how will we address:
- version control (how do I know I'm reading the most recent, can I see the
history of changes?)
- history of changes (who made which change when?)
- discussion outside of review.openstack.org from our broad community
(offering feedback loops after publishing a resolution)
- search across governance documents (inside site and across all *.
openstack.org properties)
- bug tracking and reporting (offering a feedback loop and ways to track
issues and fixes to published content)

I'm reluctant to have these published to docs.openstack.org rather than
wiki.openstack.org because of needing mechanisms to take care of those
requirements listed above. I'm bringing it up here to discuss further ---
possibly my concerns can be assuaged but I need a discussion outside of the
patch at https://review.openstack.org/#/c/61380/ so I can more clearly
illustrate my concerns.

To offer two alternative proposals:
- create a publish-rst-to-openstack-wiki build
- create governance documents that are authored in a format that then look
fine in https://github.com/openstack/governance/ or
http://git.openstack.org/cgit/openstack/governance/

Let's take a look at the bigger picture and talk more.
Thanks,
Anne
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-tc/attachments/20131217/8241626c/attachment.html>


More information about the OpenStack-TC mailing list