<div dir="ltr"><div class="gmail_default" style="font-size:small"><br></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Tue, Dec 17, 2013 at 5:21 PM, Sean Dague <span dir="ltr"><<a href="mailto:sean@dague.net" target="_blank">sean@dague.net</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div class="im">On 12/17/2013 04:29 PM, Anne Gentle wrote:<br>
> I want to discuss the needs for publishing governance documents. I think<br>
> our requirements start as:<br>
> - need for a place for review and vote tracking on governance documents<br>
><br>
> which this moved some of our documents (reference and resolutions) out<br>
> of the wiki and into files in an openstack/governance repository.<br>
><br>
> The requirements for reading those documents seems to be changing, as<br>
> Sean and others are noting that reading these documents on <a href="http://github.com" target="_blank">github.com</a><br>
</div>> <<a href="http://github.com" target="_blank">http://github.com</a>> or <a href="http://git.openstack.org" target="_blank">git.openstack.org</a> <<a href="http://git.openstack.org" target="_blank">http://git.openstack.org</a>> is<br>
<div class="im">> dissatisfying. So <a href="https://review.openstack.org/#/c/61380/" target="_blank">https://review.openstack.org/#/c/61380/</a> is how Sean is<br>
> addressing the readability concerns I think.<br>
><br>
> I think that we need to look at the requirements beyond just reading and<br>
> into these areas, how will we address:<br>
> - version control (how do I know I'm reading the most recent, can I see<br>
> the history of changes?)<br>
</div>You would always be reading the most recent that was approved. As an<br>
example - <a href="http://docs.openstack.org/developer/tempest/" target="_blank">http://docs.openstack.org/developer/tempest/</a> (git hash in<br>
template for verification).<br>
<br>
Adding a link in the template to the source tree would be a good idea so<br>
it's easy to know how to contribute. </blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div class="im"><br>
> - history of changes (who made which change when?)<br>
<br>
</div>Part b of above<br></blockquote><div><br></div><div><div class="gmail_default" style="font-size:small">It should be relatively easy for us to add a link to the git repo URL for each source file, too, which would include the approved changes.</div>
<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div class="im"><br>
> - discussion outside of <a href="http://review.openstack.org" target="_blank">review.openstack.org</a><br>
</div>> <<a href="http://review.openstack.org" target="_blank">http://review.openstack.org</a>> from our broad community (offering<br>
<div class="im">> feedback loops after publishing a resolution)<br>
<br>
</div>That's why we have a mailing list, right?<br></blockquote><div><br></div><div><div class="gmail_default" style="font-size:small;display:inline">If</div> there<div class="gmail_default" style="font-size:small;display:inline">
is</div> a way to search gerrit for changesets to a path within a repository<div class="gmail_default" style="font-size:small;display:inline">, we could link to those, too.</div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div class="im"><br>
> - search across governance documents (inside site and across all<br>
</div>> *.<a href="http://openstack.org" target="_blank">openstack.org</a> <<a href="http://openstack.org" target="_blank">http://openstack.org</a>> properties)<br>
<br>
Note integrated search. Also, searching on <a href="http://openstack.org" target="_blank">openstack.org</a> returns those<br>
tempest docs today (top hit, above the wiki hits eveng).<br>
<div class="im"><br>
> - bug tracking and reporting (offering a feedback loop and ways to track<br>
> issues and fixes to published content)<br>
<br>
</div>This doesn't affect that in any way from the current state of things.<br>
Tracking and bug reporting for governance is currently not solved. So<br>
that's probably another item.<br>
<div class="im"><br>
> I'm reluctant to have these published to <a href="http://docs.openstack.org" target="_blank">docs.openstack.org</a><br>
</div>> <<a href="http://docs.openstack.org" target="_blank">http://docs.openstack.org</a>> rather than <a href="http://wiki.openstack.org" target="_blank">wiki.openstack.org</a><br>
> <<a href="http://wiki.openstack.org" target="_blank">http://wiki.openstack.org</a>> because of needing mechanisms to take care<br>
<div class="im">> of those requirements listed above. I'm bringing it up here to discuss<br>
> further --- possibly my concerns can be assuaged but I need a discussion<br>
> outside of the patch at <a href="https://review.openstack.org/#/c/61380/" target="_blank">https://review.openstack.org/#/c/61380/</a> so I can<br>
> more clearly illustrate my concerns.<br>
><br>
> To offer two alternative proposals:<br>
> - create a publish-rst-to-openstack-wiki build<br>
<br>
</div>So, honestly, I'm not a fan of publish to wiki, because wiki's are<br>
read-write things, and this would be write only mirroring. It breaks the<br>
assumptions around it.<br></blockquote><div><br></div><div><div class="gmail_default" style="font-size:small">+1, and I agree with Anne's suggestion in another message to use a different domain & path for publishing than "<a href="http://docs.openstack.org">docs.openstack.org</a>".</div>
<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
Also, I think I've looked at a Talk page on the OpenStack wiki all of 0<br>
times since my involvement in the project. With all the other tools in<br>
front of me doing triage of content in the wiki itself is really not<br>
part of my workflow. Which isn't that it isn't for other people. But<br>
there are only so many tool switches people can take in a day and still<br>
be productive. So my proposed fix was gerrit -> sphinx as that's what<br>
I'm familiar with, and honestly trying to get more and more of the<br>
Tempest docs that way (and use the wiki less, as we tend to mostly only<br>
have really stale things there that confuse people coming in from<br>
google). :)<br>
<div class="im"><br>
> - create governance documents that are authored in a format that then<br>
> look fine in <a href="https://github.com/openstack/governance/" target="_blank">https://github.com/openstack/governance/</a><br>
> or <a href="http://git.openstack.org/cgit/openstack/governance/" target="_blank">http://git.openstack.org/cgit/openstack/governance/</a><br>
<br>
</div>Mostly, we have the technology to make this stuff pretty and accessible<br>
to the world, with nice urls today with sphinx. You could put effort<br>
into cgit to get there, but it doesn't seem like a win, especially when<br>
the rest of the project documentation goes through this well tested<br>
pipeline.<br>
<span class=""><font color="#888888"><br>
-Sean<br>
<br>
--<br>
Sean Dague<br>
<a href="http://dague.net" target="_blank">http://dague.net</a><br>
<br>
</font></span><br>_______________________________________________<br>
OpenStack-TC mailing list<br>
<a href="mailto:OpenStack-TC@lists.openstack.org">OpenStack-TC@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-tc" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-tc</a><br>
<br></blockquote></div><br></div></div>