Open Stack

On Thu, May 17, 2018 at 10:22 AM Petr Kovar <pkovar at redhat.com> wrote:

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

I think so.  I still would like to focus on the all-in-ine [1] deployment
of TripleO for an initial deployment guide from this effort.  Having
something that is fast, approachable, well documented and easy to
understand is a great combination IMHO.

There also will not be that many steps to this kind of deployment.  However
having the CI write the various deployments incantations of composable
services would save us a lot of time.

[1] https://blueprints.launchpad.net/tripleo/+spec/all-in-one




>
>
> Cheers,
> pk
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20180517/82d1105b/attachment.html>