Open Stack

On Wed, 4 Oct 2017 09:59:34 -0500
Jay S Bryant <jungleboyj at gmail.com> wrote:

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

Doug's patch has been approved and merged so we no longer use the word
"tutorial" in openstack-manuals. If project teams could go ahead and check
that their install docs use the correct terminology (installation guide, not
tutorial), that'd be much appreciated.

Thank you,
pk