Re: [openstack-dev] [kolla][infra] How to handle doc in kolla and kolla-ansible

[Andreas Jaeger]

On 11/21/2016 08:25 PM, Steven Dake (stdake) wrote:
> Andreas,
> 
> Just thinking about all the documentation rework that would be necessary…  
> Perhaps it just confuses me ;)  I think the short term result would be mass 
> confusion as we sort out the next iteration of the documentation in this 
> structure since the docs are well tested at present and I’m a bit terrified 
> to change them ;)

;)

I haven't reviewed your docs to understand how much work it is.

Just one option:
Right now, while docs.openstack.org/developer/kolla-ansibles might get
published, that content is not linked to from anywhere. You could rework
and either not publish - or only not link to the content - and only once
the new kolla-ansible content is ready, point people to it.

Choose whatever option works best for your team ;)

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
   HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [kolla][infra] How to handle doc in kolla and kolla-ansible

[Steven Dake (stdake)]

Andreas,

Just thinking about all the documentation rework that would be necessary…  
Perhaps it just confuses me ;)  I think the short term result would be mass 
confusion as we sort out the next iteration of the documentation in this 
structure since the docs are well tested at present and I’m a bit terrified to 
change them ;)

It may be possible to solve this via a massive reorg that is well reviewed and 
-2’ed until everything can merge in one go.

Regards
-steve




On 11/21/16, 5:43 AM, "Andreas Jaeger"  wrote:

>On 2016-11-21 13:24, Steven Dake (stdake) wrote:
>> Pete,
>> 
>> The main problem with that is publishing docs to docs.oo which would
>> then confuse the reader even more then they are already confused by
>> reading our docs ;)
>> 
>> Regards
>> -steve
>> 
>> 
>> From: Pete Birley >
>> Reply-To: "OpenStack Development Mailing List (not for usage questions)"
>> > >
>> Date: Monday, November 21, 2016 at 5:11 AM
>> To: "OpenStack Development Mailing List (not for usage questions)"
>> > >
>> Subject: Re: [openstack-dev] [kolla] How to handle doc in kolla and
>> kolla-ansible
>> 
>> I think Jeffrey's raised a good point here. Though I agree we should
>> keep the development side under a single umbrella/namespace, to better
>> co-ordinate our efforts, I think it makes more sense to move the
>> end-user documentation and to the repo that it's associated with. I feel
>> this is the right approach as it makes it much less likely for users to
>> confuse/mix documents. With this in mind would it not make sense to spit
>> out the docs as follows?
>> 
>>   * Kolla: images (building/specs), contributing, development
>>   * Kolla-ansible: deployment via ansible, ansible specific specs
>>   * Kolla-kubernetes: deployment via k8s, k8s specific specs
>
>Why confusing Steve? The above sounds like a logical differentiation.
>
>You could have on the front-side of kolla an section "Deployment
>options" that links to kolla-ansible and kolla-kubernetes.
>
>And in kolla-ansible/kolla-kubernetes, you have a start file that links
>back for generic support.
>
>You can also start with one way and then change later on ;)
>
>Andreas
>-- 
> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
>  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
>   HRB 21284 (AG Nürnberg)
>GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
>
>
>__
>OpenStack Development Mailing List (not for usage questions)
>Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
>http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [kolla][infra] How to handle doc in kolla and kolla-ansible

[Jay Pipes]

On 11/21/2016 07:43 AM, Andreas Jaeger wrote:

On 2016-11-21 13:24, Steven Dake (stdake) wrote:

Pete,

The main problem with that is publishing docs to docs.oo which would
then confuse the reader even more then they are already confused by
reading our docs ;)

Regards
-steve


From: Pete Birley >
Reply-To: "OpenStack Development Mailing List (not for usage questions)"
>
Date: Monday, November 21, 2016 at 5:11 AM
To: "OpenStack Development Mailing List (not for usage questions)"
>
Subject: Re: [openstack-dev] [kolla] How to handle doc in kolla and
kolla-ansible

I think Jeffrey's raised a good point here. Though I agree we should
keep the development side under a single umbrella/namespace, to better
co-ordinate our efforts, I think it makes more sense to move the
end-user documentation and to the repo that it's associated with. I feel
this is the right approach as it makes it much less likely for users to
confuse/mix documents. With this in mind would it not make sense to spit
out the docs as follows?

  * Kolla: images (building/specs), contributing, development
  * Kolla-ansible: deployment via ansible, ansible specific specs
  * Kolla-kubernetes: deployment via k8s, k8s specific specs


Why confusing Steve? The above sounds like a logical differentiation.

You could have on the front-side of kolla an section "Deployment
options" that links to kolla-ansible and kolla-kubernetes.

And in kolla-ansible/kolla-kubernetes, you have a start file that links
back for generic support.

You can also start with one way and then change later on ;)


Yeah, I tend to agree with Andreas on this. I think general docs for 
Kolla should link to more specific docs about the Ansible or k8s 
deployments of Kolla. I don't think that is much of a burden on the user.


Best,
-jay

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [kolla][infra] How to handle doc in kolla and kolla-ansible

[Andreas Jaeger]

On 2016-11-21 13:24, Steven Dake (stdake) wrote:
> Pete,
> 
> The main problem with that is publishing docs to docs.oo which would
> then confuse the reader even more then they are already confused by
> reading our docs ;)
> 
> Regards
> -steve
> 
> 
> From: Pete Birley >
> Reply-To: "OpenStack Development Mailing List (not for usage questions)"
>  >
> Date: Monday, November 21, 2016 at 5:11 AM
> To: "OpenStack Development Mailing List (not for usage questions)"
>  >
> Subject: Re: [openstack-dev] [kolla] How to handle doc in kolla and
> kolla-ansible
> 
> I think Jeffrey's raised a good point here. Though I agree we should
> keep the development side under a single umbrella/namespace, to better
> co-ordinate our efforts, I think it makes more sense to move the
> end-user documentation and to the repo that it's associated with. I feel
> this is the right approach as it makes it much less likely for users to
> confuse/mix documents. With this in mind would it not make sense to spit
> out the docs as follows?
> 
>   * Kolla: images (building/specs), contributing, development
>   * Kolla-ansible: deployment via ansible, ansible specific specs
>   * Kolla-kubernetes: deployment via k8s, k8s specific specs

Why confusing Steve? The above sounds like a logical differentiation.

You could have on the front-side of kolla an section "Deployment
options" that links to kolla-ansible and kolla-kubernetes.

And in kolla-ansible/kolla-kubernetes, you have a start file that links
back for generic support.

You can also start with one way and then change later on ;)

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
   HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [kolla][infra] How to handle doc in kolla and kolla-ansible

[Andreas Jaeger]

On 2016-11-21 13:00, Steven Dake (stdake) wrote:
> Yup this is a real challenge to sort out properly.  I’ve included infra for 
> their guidance (thanks people :).
> 
> Here is the issue
> 
> Each package should include enough docs that it stands alone after a git 
> checkout (IMO).  We also publish docs to docs.oo which should IMO contain one 
> set of docs for the entire kolla project in the /kolla namespace.
> 
> I guess the above if what I’d want in a star trek universe.  This provides 
> best of both worlds - kolla-ansible, kolla-kubernetes, kolla documentation 
> all with their respective repositories, but merged on the docs.oo site into 
> one document.  How do you do that?  No idea.

You can link from one to the other.

But having one document where you hit next, next, next will not work.
You will always have separate documents.

> So if that isn’t a possibility, putting all in kolla repo seems to make most 
> sense to me although it slows down reviews for kolla-ansible and 
> kolla-kkubernetes docs.  We could put a reference page in the docs of 
> kolla-ansible and kolla-kubernetes to “go reference kolla”.

Common stuff in kolla, specific stuff in kolla-ansible, kolla-kubernetes?

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
   HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [kolla][infra] How to handle doc in kolla and kolla-ansible

[Steven Dake (stdake)]

Pete,

The main problem with that is publishing docs to docs.oo which would then 
confuse the reader even more then they are already confused by reading our docs 
;)

Regards
-steve


From: Pete Birley >
Reply-To: "OpenStack Development Mailing List (not for usage questions)" 
>
Date: Monday, November 21, 2016 at 5:11 AM
To: "OpenStack Development Mailing List (not for usage questions)" 
>
Subject: Re: [openstack-dev] [kolla] How to handle doc in kolla and 
kolla-ansible

I think Jeffrey's raised a good point here. Though I agree we should keep the 
development side under a single umbrella/namespace, to better co-ordinate our 
efforts, I think it makes more sense to move the end-user documentation and to 
the repo that it's associated with. I feel this is the right approach as it 
makes it much less likely for users to confuse/mix documents. With this in mind 
would it not make sense to spit out the docs as follows?

  *   Kolla: images (building/specs), contributing, development
  *   Kolla-ansible: deployment via ansible, ansible specific specs
  *   Kolla-kubernetes: deployment via k8s, k8s specific specs

- Pete

On Mon, Nov 21, 2016 at 10:13 AM, Jeffrey Zhang 
> wrote:
Then what's the case of kolla-kubernetes?

On Mon, Nov 21, 2016 at 5:54 PM, Paul Bourke 
> wrote:
> Propose all docs stay under the kolla namespace
> (http://docs.openstack.org/developer/kolla).
>
> Steve mentioned that we should try to keep all components (e.g. mailing list
> tags) under the same umbrella which I agree with.
>
> On 21/11/16 08:05, Jeffrey Zhang wrote:
>>
>> After the split, we have two projects and two develop docs[0][1].
>> These two sites have lots of duplicated lines.
>>
>> So will we split the doc site?
>> if so, we need to remove the duplicated doc in the repos.
>> if not, we need to remove one site's doc.
>>
>> [0] http://docs.openstack.org/developer/kolla
>> [1] http://docs.openstack.org/developer/kolla-ansible/
>>
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: 
> openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



--
Regards,
Jeffrey Zhang
Blog: http://xcodest.me

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: 
openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



--

[Port.direct]


Pete Birley / Director
pete@port.direct / +447446862551

PORT.DIRECT
United Kingdom
https://port.direct




This e-mail message may contain confidential or legally privileged information 
and is intended only for the use of the intended recipient(s). Any unauthorized 
disclosure, dissemination, distribution, copying or the taking of any action in 
reliance on the information herein is prohibited. E-mails are not secure and 
cannot be guaranteed to be error free as they can be intercepted, amended, or 
contain viruses. Anyone who communicates with us by e-mail is deemed to have 
accepted these risks. Port.direct is not responsible for errors or omissions in 
this message and denies any responsibility for any damage arising from the use 
of e-mail. Any opinion and other statement contained in this message and any 
attachment are solely those of the author and do not necessarily represent 
those of the company.

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [kolla][infra] How to handle doc in kolla and kolla-ansible

[Steven Dake (stdake)]

Yup this is a real challenge to sort out properly.  I’ve included infra for 
their guidance (thanks people :).

Here is the issue

Each package should include enough docs that it stands alone after a git 
checkout (IMO).  We also publish docs to docs.oo which should IMO contain one 
set of docs for the entire kolla project in the /kolla namespace.

I guess the above if what I’d want in a star trek universe.  This provides best 
of both worlds - kolla-ansible, kolla-kubernetes, kolla documentation all with 
their respective repositories, but merged on the docs.oo site into one 
document.  How do you do that?  No idea.

So if that isn’t a possibility, putting all in kolla repo seems to make most 
sense to me although it slows down reviews for kolla-ansible and 
kolla-kkubernetes docs.  We could put a reference page in the docs of 
kolla-ansible and kolla-kubernetes to “go reference kolla”.

Regards
-steve





On 11/21/16, 3:13 AM, "Jeffrey Zhang"  wrote:

>Then what's the case of kolla-kubernetes?
>
>On Mon, Nov 21, 2016 at 5:54 PM, Paul Bourke  wrote:
>> Propose all docs stay under the kolla namespace
>> (http://docs.openstack.org/developer/kolla).
>>
>> Steve mentioned that we should try to keep all components (e.g. mailing list
>> tags) under the same umbrella which I agree with.
>>
>> On 21/11/16 08:05, Jeffrey Zhang wrote:
>>>
>>> After the split, we have two projects and two develop docs[0][1].
>>> These two sites have lots of duplicated lines.
>>>
>>> So will we split the doc site?
>>> if so, we need to remove the duplicated doc in the repos.
>>> if not, we need to remove one site's doc.
>>>
>>> [0] http://docs.openstack.org/developer/kolla
>>> [1] http://docs.openstack.org/developer/kolla-ansible/
>>>
>>
>> __
>> OpenStack Development Mailing List (not for usage questions)
>> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
>
>-- 
>Regards,
>Jeffrey Zhang
>Blog: http://xcodest.me
>
>__
>OpenStack Development Mailing List (not for usage questions)
>Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
>http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev