Open Stack

On Tue, Dec 17, 2013 at 4:21 PM, Sean Dague <sean at dague.net> wrote:

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


Right now, governance and meta-project documentation goes in the wiki. I
agree with everything you and Theirry are saying. I think the base problem
is the use of docs.openstack.org domain getting overloaded.

I love the automation, but dislike the landing of docs.openstack.org as it
connotes that my program is responsible. How about
www.openstack.org/governance?

Anne



>
>         -Sean
>
> --
> Sean Dague
> http://dague.net
>
>
> _______________________________________________
> OpenStack-TC mailing list
> OpenStack-TC at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-tc
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-tc/attachments/20131218/536c9325/attachment.html>