Re: [openstack-dev] [OpenStack-docs] [telemetry] Ceilometer and Aodh install guide(s)
Hi Andreas,
Thanks for the clarification on this. We will consider the options.
Best Regards,
Ildikó
> -Original Message-
> From: Andreas Jaeger [mailto:a...@suse.com]
> Sent: June 28, 2016 20:44
> To: Ildikó Váncsa; openstack-d...@lists.openstack.org
> Cc: openstack-dev@lists.openstack.org
> Subject: Re: [OpenStack-docs] [telemetry] Ceilometer and Aodh install guide(s)
>
> On 06/28/2016 08:23 PM, Ildikó Váncsa wrote:
> > Hi Andreas,
> >
> > If we would end up moving more guides to the project tree then it will be
> > confusing having multiple top level docs folder in a
> basically code repository.
> >
> > Can that be an option to have a top level 'doc' folder and having
> > sub-folders under like 'doc/developer', 'doc/install-guide', etc.?
>
> We want the same infra-jobs for all these books and no special rules for
> one of them. Renaming doc/source to doc/developer for a large part of
> our 1100+ repos is a large undertaking...
>
> Btw. nothing stops the telemetry team to have a special "telemetry-docs"
> repository that includes some of these guides,
>
> Andreas
> --
> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: 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] [OpenStack-docs] [telemetry] Ceilometer and Aodh install guide(s)
On 06/28/2016 08:23 PM, Ildikó Váncsa wrote:
> Hi Andreas,
>
> If we would end up moving more guides to the project tree then it will be
> confusing having multiple top level docs folder in a basically code
> repository.
>
> Can that be an option to have a top level 'doc' folder and having sub-folders
> under like 'doc/developer', 'doc/install-guide', etc.?
We want the same infra-jobs for all these books and no special rules for
one of them. Renaming doc/source to doc/developer for a large part of
our 1100+ repos is a large undertaking...
Btw. nothing stops the telemetry team to have a special "telemetry-docs"
repository that includes some of these guides,
Andreas
--
Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: 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] [OpenStack-docs] [telemetry] Ceilometer and Aodh install guide(s)
Hi Rodrigo, Thanks for sharing your view on this. I will consider what other way I have to organize the docs. I tried to extract the common parts and use '.. include::' as much as possible. The patch was huge already. I'm afraid what you're saying would result in even more duplication which is not ideal. I also like having less sections the user has to check and put together as that makes it easier to follow the flow. Best Regards, /Ildikó > -Original Message- > From: Caballero Abraham, Rodrigo [mailto:rodrigo.caballero.abra...@intel.com] > Sent: June 28, 2016 18:46 > To: Ildikó Váncsa; 'Spyros Trigazis'; OpenStack Development Mailing List (not > for usage questions); openstack- > d...@lists.openstack.org > Subject: RE: [OpenStack-docs] [openstack-dev] [telemetry] Ceilometer and Aodh > install guide(s) > > snip > > > > Do you have a good proposal for structuring things? > [] > I am assuming that you have distro specific instructions mixed with > non-specific ones. > I can only suggest what has worked for me in the past. I created a common > file describing the process devoid of any instructions, > distro specific or otherwise. > Then I created distro specific procedures containing all the needed > instructions with the appropriate level of detail. > The steps on the common file serve as the headings for all distro specific > procedures. That makes the common file an excellent > introduction to all procedures while keeping the entire instructions in a > single place. > > This system is not perfect however. There is some content repetition on the > instructions side of things. > This could be avoided if we used the .. only:: directive on the instructions > side. You would then have a high level overview of the > procedure, common to all distros, and a single file containing all > instructions for all distros differentiated by the only directive. > > I guess what I am saying is that there is no magic bullet here. At the end of > the day, the content determines what modularity model > you can use, IMO. > Regards, > Rodrigo > > > > Thanks, > > /Ildikó > snip __ 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] [OpenStack-docs] [telemetry] Ceilometer and Aodh install guide(s)
Hi Andreas,
If we would end up moving more guides to the project tree then it will be
confusing having multiple top level docs folder in a basically code repository.
Can that be an option to have a top level 'doc' folder and having sub-folders
under like 'doc/developer', 'doc/install-guide', etc.?
Thanks and Best Regards,
/Ildikó
> -Original Message-
> From: Andreas Jaeger [mailto:a...@suse.com]
> Sent: June 28, 2016 15:12
> To: Ildikó Váncsa; openstack-d...@lists.openstack.org
> Cc: openstack-dev@lists.openstack.org
> Subject: Re: [OpenStack-docs] [telemetry] Ceilometer and Aodh install guide(s)
>
> On 2016-06-28 14:55, Ildikó Váncsa wrote:
> > [...]
> > I have a third less urgent question. The install-guide has it's own folder
> > at the same level where these two projects have their 'doc'
> folder. I would assume other projects have the same or similar folder for the
> developer docs. Would that be reasonable/possible to
> have one main 'doc' folder for all the docs?
>
> I understand the sentiment. The install-guide is a separate book, as
> Sean Dague called it nicely, which gets published to a different place,
> integrated into the full Install Tutorial. If you make it part of the
> developer documentation, it might integrate more nicely there but not in
> the overall cross-project Install Tutorial. Developer documentation is a
> separate book already and placing several books under doc will need even
> further changes to make it clear what goes where and how to publish.
>
> So, I think the top-level folder is the best place for this,
>
> 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] [OpenStack-docs] [telemetry] Ceilometer and Aodh install guide(s)
Hi Goutham, Thanks, I already checked your solution briefly. I will wait until there is some decision about the global way forward. If '.. only::' remains an option I might change the Ceilometer setup back. Best Regards, /Ildikó > -Original Message- > From: Ravi, Goutham [mailto:goutham.r...@netapp.com] > Sent: June 28, 2016 15:32 > To: Ildikó Váncsa; openstack-d...@lists.openstack.org > Cc: openstack-dev@lists.openstack.org > Subject: Re: [OpenStack-docs] [telemetry] Ceilometer and Aodh install guide(s) > > Hi Ildikó, > > Please take a look at the tooling in https://review.openstack.org/#/c/317152/ > - I tried preserving the ‘only::’ tags because I had a > similar concern about all the common parts to someone compiling the install > guide from time to time. We were discussing whether > this was a good solution as opposed to using ‘include’ directives with > distro-specific files referencing common sections; or ignore both > and maintain four different files (obs, debian, rdo, ubuntu) with common > sections included within each. > > Thanks, > Goutham > > On 6/28/16, 8:55 AM, "Ildikó Váncsa" wrote: > > Hi, > > I'm currently working on to move the Install Guide for Ceilometer [1] and > Aodh [2] under the project trees. I faced with a few > difficulties so far about which I would like to ask your opinion. > > First of all these two projects are under the Telemetry umbrella, so they are > not completely separate. I tried to name the services in > the documents accordingly in the files. My question here would be whether > these two guides will be included in the overall document > as two totally standalone services or we can link them together somehow? > > The other question I had in mind is in connection with removing ".. only::". > As Ceilometer is integrated with several other projects it > needs additional configuration steps, where we have distro specific steps to > follow. I chose the direction of extracting the common > parts and reused them in the distro specific files. The end result still > looks ugly and I have concerns about maintainability. We merged a > first version of the structure, but I'm happy to change if we can come up > with a better solution. Do you have suggestions on this? > > I have a third less urgent question. The install-guide has it's own folder at > the same level where these two projects have their 'doc' > folder. I would assume other projects have the same or similar folder for the > developer docs. Would that be reasonable/possible to > have one main 'doc' folder for all the docs? > > Thanks and Best Regards, > Ildikó > > [1] https://review.openstack.org/#/c/330051/ > [2] https://review.openstack.org/#/c/330048/ > > ___ > OpenStack-docs mailing list > openstack-d...@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > __ 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] [OpenStack-docs] [telemetry] Ceilometer and Aodh install guide(s)
snip > > Do you have a good proposal for structuring things? [] I am assuming that you have distro specific instructions mixed with non-specific ones. I can only suggest what has worked for me in the past. I created a common file describing the process devoid of any instructions, distro specific or otherwise. Then I created distro specific procedures containing all the needed instructions with the appropriate level of detail. The steps on the common file serve as the headings for all distro specific procedures. That makes the common file an excellent introduction to all procedures while keeping the entire instructions in a single place. This system is not perfect however. There is some content repetition on the instructions side of things. This could be avoided if we used the .. only:: directive on the instructions side. You would then have a high level overview of the procedure, common to all distros, and a single file containing all instructions for all distros differentiated by the only directive. I guess what I am saying is that there is no magic bullet here. At the end of the day, the content determines what modularity model you can use, IMO. Regards, Rodrigo > > Thanks, > /Ildikó snip __ 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] [OpenStack-docs] [telemetry] Ceilometer and Aodh install guide(s)
Hi Ildikó, Please take a look at the tooling in https://review.openstack.org/#/c/317152/ - I tried preserving the ‘only::’ tags because I had a similar concern about all the common parts to someone compiling the install guide from time to time. We were discussing whether this was a good solution as opposed to using ‘include’ directives with distro-specific files referencing common sections; or ignore both and maintain four different files (obs, debian, rdo, ubuntu) with common sections included within each. Thanks, Goutham On 6/28/16, 8:55 AM, "Ildikó Váncsa" wrote: Hi, I'm currently working on to move the Install Guide for Ceilometer [1] and Aodh [2] under the project trees. I faced with a few difficulties so far about which I would like to ask your opinion. First of all these two projects are under the Telemetry umbrella, so they are not completely separate. I tried to name the services in the documents accordingly in the files. My question here would be whether these two guides will be included in the overall document as two totally standalone services or we can link them together somehow? The other question I had in mind is in connection with removing ".. only::". As Ceilometer is integrated with several other projects it needs additional configuration steps, where we have distro specific steps to follow. I chose the direction of extracting the common parts and reused them in the distro specific files. The end result still looks ugly and I have concerns about maintainability. We merged a first version of the structure, but I'm happy to change if we can come up with a better solution. Do you have suggestions on this? I have a third less urgent question. The install-guide has it's own folder at the same level where these two projects have their 'doc' folder. I would assume other projects have the same or similar folder for the developer docs. Would that be reasonable/possible to have one main 'doc' folder for all the docs? Thanks and Best Regards, Ildikó [1] https://review.openstack.org/#/c/330051/ [2] https://review.openstack.org/#/c/330048/ ___ OpenStack-docs mailing list openstack-d...@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs __ 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] [OpenStack-docs] [telemetry] Ceilometer and Aodh install guide(s)
On 2016-06-28 14:55, Ildikó Váncsa wrote:
> [...]
> I have a third less urgent question. The install-guide has it's own folder at
> the same level where these two projects have their 'doc' folder. I would
> assume other projects have the same or similar folder for the developer docs.
> Would that be reasonable/possible to have one main 'doc' folder for all the
> docs?
I understand the sentiment. The install-guide is a separate book, as
Sean Dague called it nicely, which gets published to a different place,
integrated into the full Install Tutorial. If you make it part of the
developer documentation, it might integrate more nicely there but not in
the overall cross-project Install Tutorial. Developer documentation is a
separate book already and placing several books under doc will need even
further changes to make it clear what goes where and how to publish.
So, I think the top-level folder is the best place for this,
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
