Open Stack

Just a quick note that I've begun working on the blueprint revision. I'm
using the version posted by Nick (
https://wiki.openstack.org/wiki/Blueprint-os-admin-docs). I will be
matching up the remaining parts with that ToC. - Nermina


On Wed, Aug 21, 2013 at 10:10 PM, Anne Gentle <annegentle at justwriteclick.com
> wrote:

> Hi all,
> I wanted to circle back on these items. I've been in touch with the PTLs
> and their teams, I wrote to the dev list, then I thought some more, and it
> has taken a while.
>
> On Sun, Aug 4, 2013 at 12:12 PM, Anne Gentle <
> annegentle at justwriteclick.com> wrote:
>
>>
>>
>>
>> On Thu, Aug 1, 2013 at 3:52 PM, Tom Fifield <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>> 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.
>>
>
> I got our release manager, Thierry Carrez's response to my post to the
> openstack-dev mailing list as a good indicator that going to continuous
> release for many books would be just fine. [1]
>
> I also went to four team meetings to get input directly from the teams
> themselves for these four titles:
>
>  - Block Storage Service Administration Guide
>  - Compute Administration Guide (contains Identity and Images)
>  - Networking Administration Guide
>  - Object Storage Administration Guide
>
> I'll go through each in turn.
>
>  - Block Storage Service Administration Guide
> The team is fine with putting their config and install info into other
> books, and that leaves only the "Managing Volumes" chapter in this title.
> This patch does this reorg work: https://review.openstack.org/#/c/40451/.
> After that patch goes through, if we can find a home for "Managing
> Volumes," perhaps in the Ops Guide, not sure yet, then we can eliminate
> this separate book. Sorry that the patch has gotten a little large, it
> wasn't my intent (to have that large of a patch). Hopefully this
> explanation helps.
>
>  - Compute Administration Guide (contains Identity and Images)
>
> The nova team is also fine with whatever we as a doc team think is best.
> Lots of trust there! :) We've done a lot of gutting of this guide, and it
> still has some content that doesn't have a home. Specifically:
> Overall architecture
> Identity Management
> Image Management
> Networking with nova-network
> System Administration
> OpenStack Interfaces
> Security Hardening
> OpenStack Compute Automated Installations
> Compute Tutorials
> Troubleshooting
>
> I think these can all find other homes, but I'm not exactly sure where
> yet. The patch I refer to above does some of the moving as well.
>
>  - Networking Administration Guide
> This team is also fine with removing config information and placing it in
> the Config Reference. However, this is one guide that I'm not convinced we
> should completely eliminate. It contains use cases for configuration and a
> high availability chapter and some plugin scenarios that aren't any where
> else. It's possible the use cases and "Under the Hood" could go into the
> Configuration Reference, but there are also advanced ops features like
> logging, notifications, and quotas in this guide. The neutron doc bug is
> used for 7 doc bugs, so compared to nova's 100+ doc bugs, is this guide
> actually in okay shape to keep as its own book. It seems like it to me but
> I want more input. What do you all think?
>
>  - Object Storage Administration Guide
> This team is fine with removal from openstack-manuals once all the info is
> correctly placed. For example, Configuring Object Storage with the S3 API
> needs to go to the Configuration Reference. Tom has a WIP patch going on
> right now that scrapes their sample configs and puts them into tables,
> thankfully getting rid of the raw.github.com links I had placed,
> https://review.openstack.org/#/c/43032/. Thanks Tom!
>
> These are the chapters and sections that need to find a new home:
> OpenStack Object Storage Tutorials
> Object Storage Monitoring
>
> All this said, the remaining content of three Admin guides could be
> either:
> the starting point for an OpenStack Administration Guide
>  or
> moved into the Operations Guide.
>
> Nick and/or Nermina, are you willing to do a patch for review that brings
> the remaining parts into an OpenStack Admin guide or is that too
> "Frankendoc" (trying to revive dead parts to make a whole?) Or do these
> final parts belong in the Operations Guide? We have about 2 and a half
> weeks before Docs Boot Camp, seems like enough time to get a WIP patch to
> see how it looks. Interested?
>
> Thanks again for patience and all this analysis. I do realize I haven't
> attended keystone and glance weekly meetings, but their portions are small
> and I wanted to get this out now. I'll talk to them next.
>
> Thanks,
>
> Anne
>
> 1.
> http://lists.openstack.org/pipermail/openstack-dev/2013-August/013352.html
>
>
>>
>> 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.
>>>
>>
>> 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 or 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
>>>
>>>
>>>
>>>
>>>
>>
>>
>> --
>> Anne Gentle
>> annegentle at justwriteclick.com
>>
>
>
>
> --
> Anne Gentle
> annegentle at justwriteclick.com
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>


-- 
Thank you!

Nermina Miller
Tech Writer and Editor
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130823/a95f4ec1/attachment.html>