Open Stack

Hello everyone,

Here's the preliminary blueprint:
https://wiki.openstack.org/wiki/Blueprint-os-admin-docs.

I need to clean it up a little, but most of it is there.

Please do send me some feedback regarding the layout, purpose and the next
steps.

Thanks!

Nermina




On Fri, Aug 23, 2013 at 1:35 PM, Anne Gentle <anne at openstack.org> wrote:

>
>
>
> On Fri, Aug 23, 2013 at 11:46 AM, Nermina Miller <nerminamiller at gmail.com>wrote:
>
>> 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
>>
>>
>>
> Good thinking. A patch is nice but a blueprint helps us all see the
> history. To me, that ToC is still too big... can you remove install and
> config info and then match up remaining parts?
>
> Also I want Diane to get further on the Admin User Guide so we have a good
> chance to step back and look at that. I know you've been in there, do you
> see a difference between an Admin Guide and an Admin User Guide?
>
> For next tasks per guide here's what I envision:
>
> Nermina: Pare down the "OpenStack Admin Guide" outline/blueprint based on
> what's leftover now
> Action: Find someone to pare down the Network Admin Guide -- does config
> info remain in that specific guide? Not sure. Anne to ask Edgar.
> Anne: Remove the Object Storage Admin Guide folder and move relevant info
> to new homes. https://bugs.launchpad.net/openstack-manuals/+bug/1216037
> Diane: Complete Admin User Guide (prior to Docs Boot Camp)
> Done: Pare down the Block Storage Admin Guide.
>
> More embedded below.
>
>
>> 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.
>>>
>>>
> This patch is now merged.
>
>
>>   - 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.
>>>
>>>
> Nermina, hopefully you find new homes for these. These can also be deleted
> if they are outdated and inaccurate.
>
>
>>   - 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?
>>>
>>>
> I'm going to ask Edgar Magana if he can take a look. I triaged more doc
> bugs for neutron/quantum and there's more like 20 doc bugs so they're not
> in really great shape.
>
>
>>   - 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?
>>>
>>>
> Yeah maybe I'm getting ahead of myself and really I want a blueprint and
> outline not a patch quite yet. :) Thanks Nermina!
> Anne
>
>
>>  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
>>>>
>>>
>>>
>>> _______________________________________________
>>> 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
>>
>


-- 
Thank you!

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