Open Stack

On 09/05/16 10:54, Thomas Goirand wrote:
> On 05/08/2016 11:42 AM, Andreas Jaeger wrote:
>> On 05/07/2016 11:15 AM, Thomas Goirand wrote:
>>> Hi,
>>>
>>> During the Austin summit, I could discuss with Lana about what could be
>>> done for the Debian support in the install-guide.
>>>
>>> Currently, there's these facts:
>>> - The Debconf support adds lots of conditionals which aren't easy to
>>> support (ie: it makes the individual foo-install.rst more complicated).
>>> - Some people would prefer to document the non-interactive mode.
>>> - Some people (like me) would still prefer to keep supporting using
>>> Debconf during the installation.
>>>
>>> As a consequence, we believe the most easy way forward is as follow:
>>> - Keep Debian support directly in the install-guide.
>>> - Remove conditionals for Debian using Debconf in the foo-install.rst
>>> files, and document there the DEBIAN_FRONTEND=noninteractive mode.
>>
>> Exactly, that's what we all agreed on in the Install Guide session in
>> Austin.

+1

>>
>>> - Push Debconf support in separate foo-debconf-install.rst files, and
>>> use them to generate the install-guide instead of the normal files.
>>
>> I don't understand what you want to do here - and especially how you do
>> this to make it in a way that is easy to support.
> 
> Lets take an actual example. For setting-up glance, we have
> glance-install.rst. My proposal is to create a
> glance-debconf-install.rst which will be used only in the case of Debian
> when using Debconf. This file will be less than 30 lines in this case
> (as mostly, "apt-get install glance" is the only thing there is to
> document). It will be used instead of glance-install.rst, which would go
> out of that guide.

It sounds like you want to publish a second Debian Install Guide from the same Install Guide source? If that's correct, it's not the direction we would like to go in. I'm all for you publishing a Debian guide that uses debconf, but it would need to be a separate book. We will also hopefully be publishing  other automated ways of installing as well, so it will be in good company.

> 
>> We discussed briefly in the meeting a Debconf guide and our consensus
>> was that any *automatic* setup would be done in a separate repository.
> 
> There's nothing automatic in Debconf, everything is still prompted. So
> if this was the consensus, it's built around a wrong assumption.
> 
> BTW, I'd be very careful with things discussed "briefly" and the feeling
> that there's a "consensus" in a room with only a small subset of
> everyone there. Our past discussions showed there was no such a general
> consensus.
> 
> But anyway, I'm trying to make the effort to go on the direction of the
> doc's team, and finding an arrangement that will make everyone happy, so
> let's not discuss that, and hopefully, you will agree with my current plan.
> 
>> Sourcing an additional debconf guide looks likes making everything much
>> more difficult...
> 
> Right now, if I understand correctly, the problem is that we have rather
> big files, like glance-install.rst (ie: 330 lines), which the Debconf
> implementation replaces by only a few lines. So instead of having 300
> lines full of conditionals for this reason, we move it to the index,
> which will be the only place to change.
> 
> Wont it be a lot easier this way? If not, then this plan is wrong, and
> should be rethought. But I really don't see how it will become harder.
> The index files are not touched often, they are very simple and short.
> Having a conditional there will be trivial to manage, and we wont have
> issues with alignment, which showed to be very painful in the
> *-install.rst individual files.
> 
>> Let's do this in steps:
>>
>> * Get existing guide building for Debian again
>> * Rework existing guide so that it uses the non-interactive mode
>> * Write a spec explaining how your debconf guide should look like and
>> discuss that.
>> * Implement that spec
> 
> Unfortunately, the schedule you're talking about above doesn't match the
> workflow that I am thinking of. I'd like to *move* some of the debconf
> content to some new foo-debconf-install.rst instead of foo-install.rst,
> keeping the screenshots, links and all. My intention was to work chapter
> by chapter, instead of a huge patch. It wouldn't be convenient to delete
> the content, write the spec, then re-add things back again.
> 
> Also, I doubt that we need a spec for implementing this. We're also all
> short in time, I can already foresee the spec taking months to be
> approved, with comments on the English wording of the spec and so on...
> Please let's avoid this and simply discuss it in this list!

We're usually not too slow approving specs, especially at this point in the cycle. Please create one.

Cheers,
Lana

-- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 538 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20160509/50f59e97/attachment-0001.pgp>