Open Stack

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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130823/130aa31f/attachment-0001.html>