[openstack-dev] [docs][ptls][install] Install guide vs. tutorial

Jay S Bryant jungleboyj at gmail.com
Wed Oct 4 14:59:34 UTC 2017



On 9/29/2017 3:27 PM, Doug Hellmann wrote:
> Excerpts from Petr Kovar's message of 2017-09-29 21:09:02 +0200:
>> On Tue, 26 Sep 2017 18:53:04 -0500
>> Jay S Bryant <jungleboyj at gmail.com> wrote:
>>
>>>
>>> On 9/25/2017 3:47 AM, Alexandra Settle wrote:
>>>>    
>>>>       > I completely agree consistency is more important, than bike shedding over the
>>>>       > name :)
>>>>       > To be honest, it would be easier to change everything to ‘guide’ – seeing as
>>>>       > all our URLs are ‘install-guide’.
>>>>       > But that’s the lazy in me speaking.
>>>>       >
>>>>       > Industry wise – there does seem to be more of a trend towards ‘guide’ rather
>>>>       > than ‘tutorial’. Although, that is at a cursory glance.
>>>>       >
>>>>       > I am happy to investigate further, if this matter is of some contention to
>>>>       > people?
>>>>       
>>>>       This is the first time I'm hearing about "Install Tutorial". I'm also lazy, +1
>>>>       with sticking to install guide.
>>>>       
>>>> Just to clarify: https://docs.openstack.org/install-guide/ The link is “install-guide” but the actual title on the page is “OpenStack Installation Tutorial”.
>>>>
>>>> Apologies if I haven’t been clear enough in this thread! Context always helps :P
>>>>
>>> Oy!  The URL says guide but the page says tutorial?  That is even more
>>> confusing.  I think it would be good to make it consistent and just with
>>> guide then.  All for your laziness when it leads to consistency.  :-)
>> Yes, this inconsistency in document naming is totally something we need
>> to change, hopefully based on the outcome of this discussion.
>>
>> At the PTG, I was leaning towards "tutorial" because previously, the docs
>> team chose that term to distinguish an installation HOWTO (describing
>> installing a PoC environment from packages) from a more general guide on
>> installation (possibly documenting different methods that different
>> audiences can use).
>>
>> But I could go with both.
>>
>> Cheers,
>> pk
>>
> Everyone seems rather flexible on this, so I think we just need someone
> to pick a name.
>
> Using "tutorial" will involve renaming the directory containing all of
> the content and updating the way that is published in openstack-manuals.
>
> Using "guide" will involve changing the contents of the documents
> inside a few files in openstack-manuals to match where it is already
> published, and we can do that with sed.
>
> My vote is to do the simple thing, and change the file contents:
> https://review.openstack.org/508608
>
> Doug
>
+2

I think keeping it simple, if no one has strong objections, is the best 
way to go.

-Jay

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




More information about the OpenStack-dev mailing list