Open Stack

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.abraham at intel.com]
> Sent: June 28, 2016 18:46
> To: Ildikó Váncsa; 'Spyros Trigazis'; OpenStack Development Mailing List (not for usage questions); openstack-
> docs at 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?
> [<rcaballeroMX>]
> 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