Open Stack

Excerpts from Sean McGinnis's message of 2017-09-19 16:57:40 -0500:
> > > On 9/19/17, 2:43 PM, "Eric Fried" <openstack at fried.cc> wrote:
> > >
> > >     Alex-
> > >     
> > >         Regardless of what the dictionary might say, people associate the word
> > >     "Tutorial" with a set of step-by-step instructions to do a thing.
> > >     "Guide" would be a more general term.
> > >     
> > >         I think of a "Tutorial" as being a *single* representative path through
> > >     a process.  A "Guide" could supply different alternatives.
> > >     
> > >         I expect a "Tutorial" to get me from start to finish.  A "Guide" might
> > >     help me along the way, but could be sparser.
> > >     
> > >         In summary, I believe the word "Tutorial" implies a very specific
> > >     thing, so we should use it if and only if the doc is exactly that.
> 
> I don't think we'll get consensus on this, as my association with those words
> do not match Eric's. :)
> 
> For me, a tutorial is something that teaches. So after I've gone through a
> tutorial I would expect to have learned how installs work and would just know
> these things (with an occasional need to reference a few points) going forward.
> 
> A guide to me is something that I know I will use whenever I need to do
> something. So for me, having an installation guide is what I would expect
> from this as every time I need to do a package based install, I am going to pull
> up the guide to go through it.
> 
> Sean
> 

One of the other distinctions I remember being made when this came
up last week was that the documentation we have about installation
only includes information about one of many possible ways to install
the components that it covers.

What do other projects call the document that explains similar
information? Is there some sort of general consensus in the rest of the
open source community about what term to use?

Doug