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

Jay S Bryant jungleboyj at gmail.com
Wed Sep 20 13:05:04 UTC 2017

On 9/19/2017 4:57 PM, Sean McGinnis wrote:
>>> 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
> __________________________________________________________________________
> 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

So Sean has the opposite impression from Eric and I.  Yeah, that does 
make it seem like reaching a consensus will be difficult.

At that point I think consistency becomes the most important thing.


More information about the OpenStack-dev mailing list