Open Stack

On 05/08/13 03:12, Anne Gentle wrote:
>
>
>
> On Thu, Aug 1, 2013 at 3:52 PM, Tom Fifield <tom at openstack.org
> <mailto:tom at openstack.org>> wrote:
>
>     On 02/08/13 06:43, Anne Gentle wrote:
>      >
>      >
>      >
>      > On Thu, Aug 1, 2013 at 3:27 PM, Tom Fifield <tom at openstack.org
>     <mailto:tom at openstack.org>
>      > <mailto:tom at openstack.org <mailto:tom at openstack.org>>> wrote:
>      >
>      >     > The titles that we'll release Oct 17th, regardless of number of
>      >     bugs, are:
>      >     >
>      >     >  - Compute Administration Guide (contains Identity and Images)
>      >
>      >
>      >     I disagree with releasing inaccurate information, and would
>     instead opt
>      >     for incomplete documentation. Very important distinctions in
>     types of
>      >     bugs - those that denote something missing and those that denote
>      >     something is wrong.
>      >
>      >     Then, I believe that just verifying the accuracy of the
>     information in
>      >     the Compute Administration Guide (i.e. we don't have bugs for
>     many areas
>      >     that are potentially wrong) is going to take a lot of effort,
>     and I have
>      >     yet to see where this will come from.
>      >
>      >     My suggestion would be to focus on the documents that we can make
>      >     accurate prior to release and publish the 'full library' at a
>     later
>      >     date.
>      >
>      >
>      > So nice to have you in our time zone Tom. :)
>      >
>      > I think the actual design layout will help us realize that "releases"
>      > will look different for Havana. We won't have that redesign for a few
>      > weeks, so we're talking abstractedly but have concrete views already
>      > cemented.
>      >
>      > I'm asserting that the only guides that we can ever guarantee to be
>      > synchronized with released code are install and config
>     (automated). All
>      > others are released continuously. Yes it means inaccuracies may exist
>      > but bugs exist in the code too. We can certainly leave out entire
>      > sections or chapters if they're just too buggy.
>      >
>      > I don't think that there will be a Havana Compute Administration
>     Guide
>      > on October 17th, there will be a "continuously published from master"
>      > Compute Administration Guide.
>      >
>      > The ownership is what concerns me -- Neutron "owns" their Networking
>      > Admin Guide, so does Cinder. Nova and Swift, not so much
>     ownership. So
>      > are you proposing removal of Compute Admin Guide and Object Storage
>      > Admin Guide until owners step up? I can certainly consider that here.
>      >
>      > I think we agree -- its just that the full Havana library is just two
>      > books. The rest of the books are on the shelf with a published
>     date on
>      > them. I hope the redesign will help users understand this.
>
>     Using Jet Lag to advantage :)
>
>     So yes - I am leaning towards 'not having' as a consideration.
>
>
>
> So here's where I'm at while mulling it over for a while... I don't
> think we get rid of the Admin Guide titles, yet. (Titles. Contents I can
> completely delete or move without a problem.) I think we delete contents
> until only accurate content is in them. But, we also need to have this
> conversation on the openstack-dev list. I started it here on
> openstack-docs but these are documents that belong to everyone and we
> need to expand our conversation. I'll get that post out Monday.
>
> Also, soon we'll have more info about the redesign and we can revisit
> then again. Hopefully this week I'll have the draft redesign which fixes
> the problem with people reading outdated info because the release info
> is hard to find. (bug 1191447)
> https://bugs.launchpad.net/openstack-manuals/+bug/1191447 This redesign
> may help us shape the title list as well.
>
>     I disagree that we should be publishing inaccurate information.
>     If we can't verify that it's OK, it shouldn't be on an official document
>     on openstack.org <http://openstack.org>.
>
>
> This statement is not one I can back or support. We need to be careful
> about throwing around words like "official" because there are a lot of
> grassroots efforts around docs, training, HA, and I do not want to
> squelch those efforts or discourage them in any way by raising the bar
> way too high for contributing to docs.openstack.org
> <http://docs.openstack.org> or api.openstack.org
> <http://api.openstack.org>.  I can support statements like "we strive
> for accuracy and test as throughly as possible" but I cannot back
> anything strongly stated about "official" because the Board and the TC
> are still working through "what is core?" and other such important
> questions. Read more at
> http://robhirschfeld.com/2013/07/24/what-is-core-strawman/ if you want
> some background, it's important we all understand what we're working
> through as a community.
>
>
>     What needs to happen, in my opinion, is a complete gutting of the
>     guides, and sections only added back in when they have been verified to
>     be technically accurate (potentially also copyedited, scoped and
>     structured ^_^). I disagree that just because something is 'continously
>     published' means that this step can be avoided.
>
>
> Gutting is happening now. I believe the Compute Admin Guide especially
> will be quite gutted.
>
> Hope this helps - thanks for keeping the feedback going and look for the
> discussion with the wider community this week.
> Anne
>
>     Regards,
>
>
>     Tom

Cool, seems like we agree: keep the title, massacre the content. I'm 
happy to water down the "official" word. Here's another take:

"""
Program Name: OpenStack Documentation
PTL: Anne Gentle
Mission Statement: Provide documentation for core OpenStack projects to 
promote OpenStack. Develop and maintain tools and processes to ensure 
quality, accurate documentation. Treat documentation like OpenStack code.
"""

We're treating documentation "like OpenStack code" - which means 
documentation is tested prior to committing to the repository.


Better?


Regards,


Tom