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

Sean McGinnis sean.mcginnis at gmx.com
Tue Sep 19 21:57:40 UTC 2017

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


More information about the OpenStack-dev mailing list