Re: [openstack-dev] [docs][ptls][install] Install guide vs. tutorial
On Wed, 4 Oct 2017 09:59:34 -0500 Jay S Bryant 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 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 __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [docs][ptls][install] Install guide vs. tutorial
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 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. -Jay __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [docs][ptls][install] Install guide vs. tutorial
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 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 __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [docs][ptls][install] Install guide vs. tutorial
On Tue, 26 Sep 2017 18:53:04 -0500 Jay S Bryant 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 __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [docs][ptls][install] Install guide vs. tutorial
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. :-) Jay __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [docs][ptls][install] Install guide vs. tutorial
> 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 __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [docs][ptls][install] Install guide vs. tutorial
On 11:33 Sep 21, Alexandra Settle wrote: > > 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. > > >Interesting. > > 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. > > > 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. -- Mike Perez signature.asc Description: PGP signature __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [docs][ptls][install] Install guide vs. tutorial
> 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. > Interesting. 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. 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? __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [docs][ptls][install] Install guide vs. tutorial
On 9/19/2017 4:57 PM, Sean McGinnis wrote: On 9/19/17, 2:43 PM, "Eric Fried" 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-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev Interesting. 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. Jay __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [docs][ptls][install] Install guide vs. tutorial
Excerpts from Sean McGinnis's message of 2017-09-19 16:57:40 -0500: > > > On 9/19/17, 2:43 PM, "Eric Fried" 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 __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [docs][ptls][install] Install guide vs. tutorial
> > On 9/19/17, 2:43 PM, "Eric Fried" 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-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [docs][ptls][install] Install guide vs. tutorial
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" 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-requ...@lists.openstack.org?subject:unsubscribe > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > > > __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [docs][ptls][install] Install guide vs. tutorial
Alex, I have been working on getting updates to the Cinder Installation Tutorial ... Hadn't really even considered the word Tutorial in there to be honest as it just fit. So, I think the important thing is that the pages be consistent in the terminology. It looks like the common top level documentation uses 'tutorial'. I think we would want all the other pages to follow the same convention. Jay On 9/19/2017 7: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-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [docs][ptls][install] Install guide vs. tutorial
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-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev