Open Stack

The deadline is dodgy for the scrub, I agree. Is the docs deadline 10/17 or
are we shooting for something earlier than that? I think the migration and
style cleanup can happen before then. And then we keep it agile, we keep it
lean :) I'll have Mirantis SMEs review the docs as we move along and we'll
see how far we get. What do you all think?


On Fri, Aug 30, 2013 at 3:47 PM, Anne Gentle <anne at openstack.org> wrote:

> I think you're targeting Havana but I'm not sure you can make that date,
> are you feeling confident in the move?
>
> Also, Diane is off today and Monday.
>
> Thanks for the outline - let's find good next steps.
> Anne
>
>
> On Fri, Aug 30, 2013 at 10:37 AM, Nermina Miller <nerminamiller at gmail.com>wrote:
>
>> Hello docs team!
>>
>> Ok, I have tweaked the blueprint a little:
>> https://wiki.openstack.org/wiki/Blueprint-os-admin-docs. Again, this is
>> the blueprint for what is supposed to be the new Cloud Administration
>> Guide, pieced out from the individual component guides.
>>
>> Diane, if everyone is on board with this plan, could we create a new git
>> folder for this new guide and make a plan for migration of the different
>> parts into it?
>>
>> Thank you all!
>>
>> Nermina
>>
>>
>> On Thu, Aug 29, 2013 at 12:42 AM, Nermina Miller <nerminamiller at gmail.com
>> > wrote:
>>
>>> 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
>>>
>>
>>
>>
>> --
>> 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/20130830/9b448c30/attachment-0001.html>