Open Stack

----- Original Message -----
> From: "Tom Fifield" <tom at openstack.org>
> To: "Steve Gordon" <sgordon at redhat.com>
> Cc: openstack-docs at lists.openstack.org
> Sent: Thursday, August 1, 2013 6:06:19 PM
> Subject: Re: [Openstack-docs] Common content strategy?
> 
> On 02/08/13 08:00, Steve Gordon wrote:
> > ----- Original Message -----
> >> From: "Tom Fifield" <tom at openstack.org>
> >> To: "Steve Gordon" <sgordon at redhat.com>
> >> Cc: openstack-docs at lists.openstack.org
> >> Sent: Thursday, August 1, 2013 5:27:22 PM
> >> Subject: Re: [Openstack-docs] Common content strategy?
> >>
> >> On 02/08/13 07:26, Steve Gordon wrote:
> >>> ----- Original Message -----
> >>>> From: "Tom Fifield" <tom at openstack.org>
> >>>> To: "Steve Gordon" <sgordon at redhat.com>
> >>>> Cc: openstack-docs at lists.openstack.org
> >>>> Sent: Thursday, August 1, 2013 4:58:41 PM
> >>>> Subject: Re: [Openstack-docs] Common content strategy?
> >>>>
> >>>> On 02/08/13 06:17, Steve Gordon wrote:
> >>>>> ----- Original Message -----
> >>>>>> From: "Tom Fifield" <tom at openstack.org>
> >>>>>> To: "Steve Gordon" <sgordon at redhat.com>
> >>>>>> Cc: openstack-docs at lists.openstack.org
> >>>>>> Sent: Thursday, August 1, 2013 4:08:35 PM
> >>>>>> Subject: Re: [Openstack-docs] Common content strategy?
> >>>>>>
> >>>>>> On 02/08/13 06:06, Steve Gordon wrote:
> >>>>>>> ----- Original Message -----
> >>>>>>>> From: "Tom Fifield" <tom at openstack.org>
> >>>>>>>> To: openstack-docs at lists.openstack.org
> >>>>>>>> Sent: Thursday, August 1, 2013 3:53:54 PM
> >>>>>>>> Subject: Re: [Openstack-docs] Common content strategy?
> >>>>>>>>
> >>>>>>>> Just quickly on the crazy linking that's going on right now.
> >>>>>>>>
> >>>>>>>> I'm one of the worst offenders of breaking the model, but I believe
> >>>>>>>> there's good reason ... in doing the restructure, I'm trying to keep
> >>>>>>>> current things in place, but note that they'll be subsumed as
> >>>>>>>> further
> >>>>>>>> progress is made.
> >>>>>>>>
> >>>>>>>> If there's a big effort to push content into the common folder right
> >>>>>>>> now, you'll end up with most of the compute admin manual and the
> >>>>>>>> config
> >>>>>>>> reference in the common folder.
> >>>>>>>
> >>>>>>> Given at this stage the intent is to continue to release the compute
> >>>>>>> administration guide isn't that correct though (in that the content
> >>>>>>> *is*
> >>>>>>> common to both)? Keep in mind here also that large swaths of the
> >>>>>>> compute
> >>>>>>> admin manual already appear in common (this is in part why I brought
> >>>>>>> up
> >>>>>>> the taxonomy question).
> >>>>>>
> >>>>>> Not for the next release, unless you want to write it :)
> >>>>>
> >>>>> OK, it was still listed last I saw - just not as one of the two
> >>>>> deliverables that must be ready:
> >>>>>
> >>>>> http://lists.openstack.org/pipermail/openstack-docs/2013-July/002391.html
> >>>>
> >>>> Yep, I disagree with this, so I've replied to that thread :)
> >>>>
> >>>>>> Additionally, the content in config ref that is currently xi:included
> >>>>>> will be struck from the compute admin guide - it will not be common to
> >>>>>> both.
> >>>>>
> >>>>> Right, but to me that is all the more reason to do it now. As it
> >>>>> currently
> >>>>> stands without any of my commits on this issue being merged there are
> >>>>> ~144
> >>>>> relative includes in openstack-config, of those only 10 go to locations
> >>>>> outside of common (which are the ones I want to move).
> >>>>
> >>>> So https://review.openstack.org/#/c/39731 is an example of where this
> >>>> consolidation is a bad idea right now :)
> >>>>
> >>>> I'm in the middle of working through re-doing which xen bit sit wher,
> >>>> and would just end up un-doing the move proposed in the patch.
> >>>
> >>> The problem though is bits and pieces of that redo are already committed,
> >>> resulting in this kind of structure:
> >>>
> >>> * openstack-config/ch_computehypervisors.xml
> >>>     * Includes -> ../common/introduction-to-xen.xml
> >>>       * Includes -> ../openstack-config/compute-configure-xen.xml
> >>>         * Includes -> ../common/tables/nova-xen.xml
> >>>
> >>> Are you suggesting that your approach to this will be to move the 3/4
> >>> files
> >>> in this chain that are in common now to openstack-config, rather than the
> >>> opposite as proposed in my patch? If the plan is for these files to move
> >>> to openstack-config and be dropped from the other guide(s) then I'd
> >>> suggest making a list and let's get it done.
> >>
> >> Yes
> >>
> >
> > OK, what is the expected final resting place of these others that I have
> > come across in my travels (cases where openstack-config includes content
> > from other guides that is not in common):
> >
> > openstack-config/ch_blockstorageconfigure.xml:
> > "../openstack-install/samples/cinder.conf"
> > openstack-config/ch_computeconfigure.xml:
> > "../openstack-install/samples/nova.conf"
> > openstack-config/ch_computeconfigure.xml:
> > "../openstack-install/samples/nova.conf"
> > openstack-config/ch_computeconfigure.xml:
> > "../openstack-compute-admin/figures/SCH_5004_V00_NUAC-Network_mode_KVM_Flat_OpenStack.png"
> > openstack-config/ch_computeconfigure.xml:
> > "../openstack-compute-admin/figures/SCH_5005_V00_NUAC-Network_mode_XEN_Flat_OpenStack.png"
> > openstack-config/ch_computescheduler.xml:
> > "../openstack-compute-admin/figures/filteringWorkflow1.png"
> > openstack-config/ch_computescheduler.xml:
> > "../openstack-compute-admin/figures/filteringWorkflow2.png"
> > openstack-config/ch_identityconfigure.xml:
> > "../openstack-install/samples/keystone.conf"
> >
> > Are these also cases where the content will be removed from the original
> > guide?
> 
> Possibly :)
> 
> The point here is that there's tons of crazy work going on where content
> is going everywhere, and that's going to evolve over time.

I think it would be better to openly discuss where the content is going and what will/wont be duplicated in multiple guides as we go. It is clear for example that you are working off the assumption that the compute admin guide will not be published at all which is not what had previously been discussed (even though it is something I would actually be in favour of).

> I agree with the common content strategy, the problem I've got is doing
> it right now. It's like someone swapping your food from pan to pan while
> you're cooking, when it just needed a few more minutes before it was
> plated :)

I had actually already moved all shared content I could find (that wasn't already in common) to common just prior to the Grizzly release. So it's not really work I've started doing right now but rather something I've turned my attention to again only to find it all over the floor ;).

> My suggestion would be to focus on the content first - rather than the
> filenames. In performing the restructure based on content, we'll end up
> with that clarity we need to realise our common content dream.

Structure and content are intertwined and should be considered in tandem. I also don't believe if the amount of shared content outside of common is allowed to continue growing unchecked it will necessarily be as trivial to put the genie back in the bottle as you suggest.

Steve