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

Eric Fried openstack at fried.cc
Tue Sep 19 20:59:01 UTC 2017


Alex-

    The non-list reply was deliberate.  I honestly haven't looked at the
docs in question, so really my answer was just me being pedantic about
how I interpret those two words in general when I see them in technical
literature.  Jay's concerns about consistency are probably more important.

    However, posting back to the list, as requested.

Thanks,
Eric

On 09/19/2017 03:49 PM, Alexandra Settle wrote:
> Hi Eric,
>
> I’m not entirely too sure if you meant to just reply to me regarding this thread? :)
>
> However, it would be helpful if you could bring it back to the mailing list to highlight your concerns and continue this discussion :)
>
> Thanks for your reply,
>
> Alex
>
> 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.
>     
>     			Eric
>     
>     On 09/19/2017 07:23 AM, Alexandra Settle wrote:
>     > Hi everyone,
>     > 
>     >  
>     > 
>     > I hope everyone had a safe trip home after the PTG!
>     > 
>     >  
>     > 
>     > Since the doc-migration, quite a number or individuals have had
>     > questions regarding the usage of “Install Tutorial” vs. “Install Guide”
>     > in our documentation in the openstack-manuals repo and in the
>     > project-specific repos. We (the doc team) agree there should be
>     > consistency across all repos and would like to bring this to the table
>     > to discuss.
>     > 
>     >  
>     > 
>     > Previously, we have used the phrase ‘tutorial’ as the literal
>     > translation of a tutorial is that of a /‘paper, book, film, or computer
>     > program that provides practical information about a specific subject.’/
>     > 
>     > / /
>     > 
>     > Thoughts?
>     > 
>     >  
>     > 
>     > Alex
>     > 
>     > 
>     > 
>     > __________________________________________________________________________
>     > 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