<div dir="ltr"><br><br><div class="gmail_quote"><div dir="ltr">On Thu, May 17, 2018 at 10:22 AM Petr Kovar <<a href="mailto:pkovar@redhat.com">pkovar@redhat.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On Wed, 16 May 2018 13:26:46 -0600<br>
Wesley Hayutin <<a href="mailto:whayutin@redhat.com" target="_blank">whayutin@redhat.com</a>> wrote:<br>
<br>
> On Wed, May 16, 2018 at 3:05 PM Doug Hellmann <<a href="mailto:doug@doughellmann.com" target="_blank">doug@doughellmann.com</a>> wrote:<br>
> <br>
> > Excerpts from Wesley Hayutin's message of 2018-05-16 12:51:25 -0600:<br>
> > > On Wed, May 16, 2018 at 2:41 PM Doug Hellmann <<a href="mailto:doug@doughellmann.com" target="_blank">doug@doughellmann.com</a>><br>
> > wrote:<br>
> > ><br>
> > > > Excerpts from Petr Kovar's message of 2018-05-16 17:39:14 +0200:<br>
> > > > > Hi all,<br>
> > > > ><br>
> > > > > In the past few years, we've seen several efforts aimed at automating<br>
> > > > > procedural documentation, mostly centered around the OpenStack<br>
> > > > > installation guide. This idea to automatically produce and verify<br>
> > > > > installation steps or similar procedures was mentioned again at the<br>
> > last<br>
> > > > > Summit (<a href="https://etherpad.openstack.org/p/SYD-install-guide-testing" rel="noreferrer" target="_blank">https://etherpad.openstack.org/p/SYD-install-guide-testing</a>).<br>
> > > > ><br>
> > > > > It was brought to my attention that the tripleo team has been<br>
> > working on<br>
> > > > > automating some of the tripleo deployment procedures, using a Bash<br>
> > script<br>
> > > > > with included comment lines to supply some RST-formatted narrative,<br>
> > for<br>
> > > > > example:<br>
> > > > ><br>
> > > > ><br>
> > > ><br>
> > <a href="https://github.com/openstack/tripleo-quickstart-extras/blob/master/roles/overcloud-prep-images/templates/overcloud-prep-images.sh.j2" rel="noreferrer" target="_blank">https://github.com/openstack/tripleo-quickstart-extras/blob/master/roles/overcloud-prep-images/templates/overcloud-prep-images.sh.j2</a><br>
> > > > ><br>
> > > > > The Bash script can then be converted to RST, e.g.:<br>
> > > > ><br>
> > > > ><br>
> > > ><br>
> > <a href="https://thirdparty.logs.rdoproject.org/jenkins-tripleo-quickstart-queens-rdo_trunk-baremetal-dell_fc430_envB-single_nic_vlans-27/docs/build/" rel="noreferrer" target="_blank">https://thirdparty.logs.rdoproject.org/jenkins-tripleo-quickstart-queens-rdo_trunk-baremetal-dell_fc430_envB-single_nic_vlans-27/docs/build/</a><br>
> > > > ><br>
> > > > > Source Code:<br>
> > > > ><br>
> > > > ><br>
> > > ><br>
> > <a href="https://github.com/openstack/tripleo-quickstart-extras/tree/master/roles/collect-logs" rel="noreferrer" target="_blank">https://github.com/openstack/tripleo-quickstart-extras/tree/master/roles/collect-logs</a><br>
> > > > ><br>
> > > > > I really liked this approach and while I don't want to sound like<br>
> > selling<br>
> > > > > other people's work, I'm wondering if there is still an interest<br>
> > among<br>
> > > > the<br>
> > > > > broader OpenStack community in automating documentation like this?<br>
> > > > ><br>
> > > > > Thanks,<br>
> > > > > pk<br>
> > > > ><br>
> > > ><br>
> > > > Weren't the folks doing the training-labs or training-guides taking a<br>
> > > > similar approach? IIRC, they ended up implementing what amounted to<br>
> > > > their own installer for OpenStack, and then ended up with all of the<br>
> > > > associated upgrade and testing burden.<br>
> > > ><br>
> > > > I like the idea of trying to use some automation from this, but I<br>
> > wonder<br>
> > > > if we'd be better off extracting data from other tools, rather than<br>
> > > > building a new one.<br>
> > > ><br>
> > > > Doug<br>
> > > ><br>
> > ><br>
> > > So there really isn't anything new to create, the work is done and<br>
> > executed<br>
> > > on every tripleo change that runs in rdo-cloud.<br>
> ><br>
> > It wasn't clear what Petr was hoping to get. Deploying with TripleO is<br>
> > only one way to deploy, so we wouldn't be able to replace the current<br>
> > installation guides with the results of this work. It sounds like that's<br>
> > not the goal, though.<br>
<br>
<br>
Yes, I wasn't very clear on the goals as I didn't want to make too many<br>
assumptions before learning about technical details from other people.<br>
Ben's comments made me realize this approach would probably be best suited<br>
for generating documents such as quick start guides or tutorials that are<br>
procedural, yet they don't aim at describing multiple use cases.<br>
<br>
<br>
> > ><br>
> > > Instead of dismissing the idea upfront I'm more inclined to set an<br>
> > > achievable small step to see how well it works.  My thought would be to<br>
> > > focus on the upcoming all-in-one installer and the automated doc<br>
> > generated<br>
> > > with that workflow.  I'd like to target publishing the all-in-one tripleo<br>
> > > installer doc to [1] for Stein and of course a section of <a href="http://tripleo.org" rel="noreferrer" target="_blank">tripleo.org</a>.<br>
> ><br>
> > As an official project, why is TripleO still publishing docs to its own<br>
> > site? That's not something we generally encourage.<br>
> ><br>
> > That said, publishing a new deployment guide based on this technique<br>
> > makes sense in general. What about Ben's comments elsewhere in the<br>
> > thread?<br>
> ><br>
> <br>
> I think Ben is referring to an older implementation and a slightly<br>
> different design but still has some points that we would want to be mindful<br>
> of.   I think this is a worthy effort to take another pass at this<br>
> regarless to be honest as we've found a good combination of interested<br>
> folks and sometimes the right people make all the difference.<br>
> <br>
> My personal opinion is that I'm not expecting the automated doc generation<br>
> to be upload ready to a doc server after each run.  I do expect it to do<br>
> 95% of the work, and to help keep the doc up to date with what is executed<br>
> in the latest releases of TripleO.<br>
<br>
<br>
Would it make sense to consider a bot automatically creating patches<br>
with content updates that would be then curated and reviewed by the docs<br>
contributors?<br>
<br>
<br>
>  Also noting the doc used is a mixture<br>
> of static and generated documentation which I think worked out quite well<br>
> in order to not soley rely on what is executed in ci.<br>
> <br>
> So again, my thought is to create a small achievable goal and see where the<br>
> collaboration takes us.<br>
<br>
<br>
Is a tripleo-focused quick-start deployment guide (that would get<br>
integrated with the existing tripleo content) such a small achievable goal?<br></blockquote><div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div>[1] <a href="https://blueprints.launchpad.net/tripleo/+spec/all-in-one">https://blueprints.launchpad.net/tripleo/+spec/all-in-one</a></div><div><br></div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
<br>
Cheers,<br>
pk<br>
</blockquote></div></div>