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? > [<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 __________________________________________________________________________ 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
