Open Stack

On Wed, May 16, 2018 at 1:04 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.
>
>>
>> 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.
>

We publish on docs.o.o. It's the same docs, just different theme.

https://docs.openstack.org/tripleo-docs/latest/install/index.html
https://docs.openstack.org/tripleo-docs/latest/contributor/index.html

I guess we could just change the tripleo.org to redirect to the
docs.o.o stuff. I'm not sure the history behind this.  I would say
that you can't really find them from the main docs.o.o page unless you
search so maybe that's part of it? I'm assuming this is likely because
we don't version our docs in the past so they don't show up.  Is there
a better way to ensure visibility of docs?

Thanks,
-Alex

> That said, publishing a new deployment guide based on this technique
> makes sense in general. What about Ben's comments elsewhere in the
> thread?
>
> Doug
>
>>
>> What do you think?
>>
>> [1] https://docs.openstack.org/queens/deploy/
>>
>> >
>> > __________________________________________________________________________
>> > OpenStack Development Mailing List (not for usage questions)
>> > Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
>> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>> >
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev