Open Stack

On Mon, 9 May 2016 09:59:36 +0200
Andreas Jaeger <aj at suse.com> wrote:

> On 2016-05-09 02:08, Tomoyuki Kato wrote:
> > 
> >> We had some discussions in Austin on how to go forward with the Install
> >> Guides and I've wrote up a couple of steps.
> >>
> >> Note that this is not complete but something for us to discuss. Lana,
> >> please add what we agree on in your spec.
> >>
> >>
> >> 1) Cookiecutter for project specific install guides with basic
> >>   structure. Make this part of docs team repos...
> >>
> >>   First draft at:
> >>   https://github.com/ajaeger/cookiecutter-installguide
> >>
> >>   A cookiecutter allows a project to easily setup the structure for the
> >> guide. Please review what I've done and see whether that works.
> > 
> > Nice work!
> > Do we use "only" directive for each distro?
> 
> I would leave that to the project teams. Or we could give some
> recommendation on either way.
> 
> We should make a script available to build multiple distros if we
> recommend it.

So I've started looking into separating install docs for heat and am unsure
whether to keep the conditions in. Do we want a consistent approach here
or is it better to treat each project individually when creating patches
for it?
 

> > I don't want to use it to avoid complex things for Advanced Install Guide.
> > Alternatively, I'd like to add the conditional description. For example,
> > 
> >   1. install the packages:
> >       For Ubuntu,
> >               xxxx
> >       For xxxx,
> >               xxxx ....
> 
> Might be the easier way, and we could advise on doing it this way...

I think this is a good approach when there is a small number of
conditions used on a single page. If the page is heavy on conditions,
having a separate page for each distro looks better. Fwiw, that's what the
content structure in heat devel docs looks like.

Cheers,
pk

-- 
Petr Kovar
Sr. Technical Writer | Customer Content Services
Red Hat Czech, Brno