Re: [openstack-dev] [telemetry] Ceilometer and Aodh install guide(s)

2016-06-28 Thread Ildikó Váncsa 
Hi,

@Julien: +1 to the one 'doc' folder.

I think it's not yet decided whether it should be modular, using '.. only::' or 
we can/will have both.

I use the modular approach as well right now, I have many files containing the 
common things and the distro specific steps. For Ceilometer it resulted in way 
more files and folders than it should be in my opinion. And I think it will 
discourage people from contributing to it. The more files you have the harder 
to see how the guide will look like after the build, which can make it slower 
to identify and then modify the files.

Do you have a good proposal for structuring things?

Thanks,
/Ildikó

> -Original Message-
> From: Spyros Trigazis [mailto:strig...@gmail.com]
> Sent: June 28, 2016 17:18
> To: OpenStack Development Mailing List (not for usage questions); Ildikó 
> Váncsa; openstack-d...@lists.openstack.org
> Subject: Re: [openstack-dev] [telemetry] Ceilometer and Aodh install guide(s)
> 
> +1 on the modular approach by Rodrigo Caballero
> 
> I'm writing magnum's guide and I'm working on the debian guide. Debian's 
> guide will have a couple of differences and I plan to move
> them in other files or/and break the existing common config files.
> 
> IMO, one of the goals of the project specific guides was to let teams decide 
> what works for them. If the output guide is similar to
> others, I think you can choose what suits you best.
> 
> Cheers,
> Spyros
> 
> 
> On 28 June 2016 at 16:44, Julien Danjou <jul...@danjou.info> wrote:
> 
> 
>   On Tue, Jun 28 2016, 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?
> 
>   This is our long-term objective for Telemetry projects.
> 
>   Gnocchi already have only one doc/ folder with all the documentation,
>   From installation to usage.
> 
>   I don't think our projects are not big enough and have enough resources
>   to start maintaining different documentations with different scopes,
>   etc.
> 
>   --
>   Julien Danjou
>   ;; Free Software hacker
>   ;; https://julien.danjou.info
> 
>   
> __
>   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] [telemetry] Ceilometer and Aodh install guide(s)

2016-06-28 Thread Spyros Trigazis 
+1 on the modular approach by Rodrigo Caballero

I'm writing magnum's guide and I'm working on the debian guide. Debian's
guide will have a couple of differences and I plan to move them in other
files or/and break the existing common config files.

IMO, one of the goals of the project specific guides was to let teams decide
what works for them. If the output guide is similar to others, I think you
can
choose what suits you best.

Cheers,
Spyros


On 28 June 2016 at 16:44, Julien Danjou  wrote:

> On Tue, Jun 28 2016, 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?
>
> This is our long-term objective for Telemetry projects.
>
> Gnocchi already have only one doc/ folder with all the documentation,
> From installation to usage.
>
> I don't think our projects are not big enough and have enough resources
> to start maintaining different documentations with different scopes,
> etc.
>
> --
> Julien Danjou
> ;; Free Software hacker
> ;; https://julien.danjou.info
>
> __
> 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] [telemetry] Ceilometer and Aodh install guide(s)

2016-06-28 Thread Julien Danjou 
On Tue, Jun 28 2016, 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?

This is our long-term objective for Telemetry projects.

Gnocchi already have only one doc/ folder with all the documentation,
From installation to usage.

I don't think our projects are not big enough and have enough resources
to start maintaining different documentations with different scopes,
etc.

-- 
Julien Danjou
;; Free Software hacker
;; https://julien.danjou.info


signature.asc
Description: PGP signature
__
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] [telemetry] Ceilometer and Aodh install guide(s)

2016-06-28 Thread Caballero Abraham, Rodrigo 


> -Original Message-
> From: Ildikó Váncsa [mailto:ildiko.van...@ericsson.com]
> Sent: Tuesday, June 28, 2016 7:56 AM
> To: openstack-d...@lists.openstack.org
> Cc: openstack-dev@lists.openstack.org
> Subject: [OpenStack-docs] [telemetry] Ceilometer and Aodh install
> guide(s)
snip
> 
> 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 would suggest a modular approach with the use of .. include::
It would look something like this:

==
Instructions for Ubuntu
==

.. include:: file-with-common-steps.rst

.. include:: file-with-ubuntu-steps.rst

Then you can do the same for each distro. Having all the separate procedures
in different files should help solve your maintainability concerns.

Regards,
Rodrigo Caballero

snip
> 
> 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

[openstack-dev] [telemetry] Ceilometer and Aodh install guide(s)

2016-06-28 Thread Ildikó Váncsa 
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 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