Open Stack

On Wed, 16 May 2018 13:26:46 -0600
Wesley Hayutin <whayutin at redhat.com> wrote:

> On Wed, May 16, 2018 at 3:05 PM Doug Hellmann <doug at doughellmann.com> wrote:
> 
> > Excerpts from Wesley Hayutin's message of 2018-05-16 12:51:25 -0600:
> > > On Wed, May 16, 2018 at 2:41 PM Doug Hellmann <doug at doughellmann.com>
> > wrote:
> > >
> > > > Excerpts from Petr Kovar's message of 2018-05-16 17:39:14 +0200:
> > > > > Hi all,
> > > > >
> > > > > In the past few years, we've seen several efforts aimed at automating
> > > > > procedural documentation, mostly centered around the OpenStack
> > > > > installation guide. This idea to automatically produce and verify
> > > > > installation steps or similar procedures was mentioned again at the
> > last
> > > > > Summit (https://etherpad.openstack.org/p/SYD-install-guide-testing).
> > > > >
> > > > > It was brought to my attention that the tripleo team has been
> > working on
> > > > > automating some of the tripleo deployment procedures, using a Bash
> > script
> > > > > with included comment lines to supply some RST-formatted narrative,
> > for
> > > > > example:
> > > > >
> > > > >
> > > >
> > https://github.com/openstack/tripleo-quickstart-extras/blob/master/roles/overcloud-prep-images/templates/overcloud-prep-images.sh.j2
> > > > >
> > > > > The Bash script can then be converted to RST, e.g.:
> > > > >
> > > > >
> > > >
> > https://thirdparty.logs.rdoproject.org/jenkins-tripleo-quickstart-queens-rdo_trunk-baremetal-dell_fc430_envB-single_nic_vlans-27/docs/build/
> > > > >
> > > > > Source Code:
> > > > >
> > > > >
> > > >
> > https://github.com/openstack/tripleo-quickstart-extras/tree/master/roles/collect-logs
> > > > >
> > > > > I really liked this approach and while I don't want to sound like
> > selling
> > > > > other people's work, I'm wondering if there is still an interest
> > among
> > > > the
> > > > > broader OpenStack community in automating documentation like this?
> > > > >
> > > > > Thanks,
> > > > > pk
> > > > >
> > > >
> > > > Weren't the folks doing the training-labs or training-guides taking a
> > > > similar approach? IIRC, they ended up implementing what amounted to
> > > > their own installer for OpenStack, and then ended up with all of the
> > > > associated upgrade and testing burden.
> > > >
> > > > I like the idea of trying to use some automation from this, but I
> > wonder
> > > > if we'd be better off extracting data from other tools, rather than
> > > > building a new one.
> > > >
> > > > Doug
> > > >
> > >
> > > So there really isn't anything new to create, the work is done and
> > executed
> > > on every tripleo change that runs in rdo-cloud.
> >
> > It wasn't clear what Petr was hoping to get. Deploying with TripleO is
> > only one way to deploy, so we wouldn't be able to replace the current
> > installation guides with the results of this work. It sounds like that's
> > not the goal, though.


Yes, I wasn't very clear on the goals as I didn't want to make too many
assumptions before learning about technical details from other people.
Ben's comments made me realize this approach would probably be best suited
for generating documents such as quick start guides or tutorials that are
procedural, yet they don't aim at describing multiple use cases.


> > >
> > > Instead of dismissing the idea upfront I'm more inclined to set an
> > > achievable small step to see how well it works.  My thought would be to
> > > focus on the upcoming all-in-one installer and the automated doc
> > generated
> > > with that workflow.  I'd like to target publishing the all-in-one tripleo
> > > installer doc to [1] for Stein and of course a section of tripleo.org.
> >
> > As an official project, why is TripleO still publishing docs to its own
> > site? That's not something we generally encourage.
> >
> > That said, publishing a new deployment guide based on this technique
> > makes sense in general. What about Ben's comments elsewhere in the
> > thread?
> >
> 
> I think Ben is referring to an older implementation and a slightly
> different design but still has some points that we would want to be mindful
> of.   I think this is a worthy effort to take another pass at this
> regarless to be honest as we've found a good combination of interested
> folks and sometimes the right people make all the difference.
> 
> My personal opinion is that I'm not expecting the automated doc generation
> to be upload ready to a doc server after each run.  I do expect it to do
> 95% of the work, and to help keep the doc up to date with what is executed
> in the latest releases of TripleO.


Would it make sense to consider a bot automatically creating patches
with content updates that would be then curated and reviewed by the docs
contributors?


>  Also noting the doc used is a mixture
> of static and generated documentation which I think worked out quite well
> in order to not soley rely on what is executed in ci.
> 
> So again, my thought is to create a small achievable goal and see where the
> collaboration takes us.


Is a tripleo-focused quick-start deployment guide (that would get
integrated with the existing tripleo content) such a small achievable goal?


Cheers,
pk