Open Stack

On 12/17/2013 04:29 PM, Anne Gentle wrote:
> 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
> <http://github.com> or git.openstack.org <http://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?)
You would always be reading the most recent that was approved. As an
example - http://docs.openstack.org/developer/tempest/ (git hash in
template for verification).

Adding a link in the template to the source tree would be a good idea so
it's easy to know how to contribute.

> - history of changes (who made which change when?)

Part b of above

> - discussion outside of review.openstack.org
> <http://review.openstack.org> from our broad community (offering
> feedback loops after publishing a resolution)

That's why we have a mailing list, right?

> - search across governance documents (inside site and across all
> *.openstack.org <http://openstack.org> properties)

Note integrated search. Also, searching on openstack.org returns those
tempest docs today (top hit, above the wiki hits eveng).

> - bug tracking and reporting (offering a feedback loop and ways to track
> issues and fixes to published content)

This doesn't affect that in any way from the current state of things.
Tracking and bug reporting for governance is currently not solved. So
that's probably another item.

> I'm reluctant to have these published to docs.openstack.org
> <http://docs.openstack.org> rather than wiki.openstack.org
> <http://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

So, honestly, I'm not a fan of publish to wiki, because wiki's are
read-write things, and this would be write only mirroring. It breaks the
assumptions around it.

Also, I think I've looked at a Talk page on the OpenStack wiki all of 0
times since my involvement in the project. With all the other tools in
front of me doing triage of content in the wiki itself is really not
part of my workflow. Which isn't that it isn't for other people. But
there are only so many tool switches people can take in a day and still
be productive. So my proposed fix was gerrit -> sphinx as that's what
I'm familiar with, and honestly trying to get more and more of the
Tempest docs that way (and use the wiki less, as we tend to mostly only
have really stale things there that confuse people coming in from
google). :)

> - 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/

Mostly, we have the technology to make this stuff pretty and accessible
to the world, with nice urls today with sphinx. You could put effort
into cgit to get there, but it doesn't seem like a win, especially when
the rest of the project documentation goes through this well tested
pipeline.

	-Sean

-- 
Sean Dague
http://dague.net

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 482 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-tc/attachments/20131217/650820c8/attachment.pgp>