, 4) ":" instead of —, 5) &ndash or "-" I've seen recently some patches using the first variant but there's a lot of variations. Do we want to have a consistent style for new changes? And which one? This was triggered by reviewing https://review.openstack.org/91736, https://review.openstack.org/90625 and then editing config-reference/compute/section_compute-cells.xml Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From tom at openstack.org Fri May 2 07:07:56 2014 From: tom at openstack.org (Tom Fifield) Date: Fri, 02 May 2014 15:07:56 +0800 Subject: [Openstack-docs] Add release version to config reference options Message-ID: <5363444C.5010801@openstack.org> Hi, Related to our critical Bug #1191447: Clearly mark outdated doc pages, I have proposed a new blueprint for Juno "Add release version to config reference options" https://blueprints.launchpad.net/openstack-manuals/+spec/add-release-version-to-config-reference-options The continuously published configuration reference contains tables with information about all configuration options in OpenStack. Currently, these tables are updated from master, and always have the latest information in them. However, there continues to be users of older releases who still need reference information for their configuration options. The toolchain used to generate the tables is able to operate on any git repository checkout, meaning it can also generate historical tables. This blueprint proposes to automatically provide some form of release information with the configuration option by comparing the options generated from two different repositories. For example * an option that appears in a Havana repository, but does not appear in an Icehouse repository was deprecated in Havana. * an option that does not exist in Grizzly, but appears in Havana is a new option to Havana These sort of cases should then be communicated to the reader. A selection between three potential forms for this information are envisaged: 1. tables are updated with an additional column that provides release information (eg "available from Icehouse onwards", "deprecated in Essex") 2. a table of "new and removed" options between Icehouse and Juno is added as an appendix 3. the configuration reference is branched for the Juno release, with different versions of the tables in each Your thoughts are desired. It's also highly unlikely I will have time to work on this myself, so if someone likes the idea so much they want to step up and do it please volunteer! Regards, Tom From aj at suse.com Fri May 2 07:21:51 2014 From: aj at suse.com (Andreas Jaeger) Date: Fri, 02 May 2014 09:21:51 +0200 Subject: [Openstack-docs] Add release version to config reference options In-Reply-To: <5363444C.5010801@openstack.org> References: <5363444C.5010801@openstack.org> Message-ID: <5363478F.5000402@suse.com> On 05/02/2014 09:07 AM, Tom Fifield wrote: > Hi, > > Related to our critical Bug #1191447: Clearly mark outdated doc pages, > I have proposed a new blueprint for Juno > > "Add release version to config reference options" > > https://blueprints.launchpad.net/openstack-manuals/+spec/add-release-version-to-config-reference-options > > > The continuously published configuration reference contains tables with > information about all configuration options in OpenStack. > > Currently, these tables are updated from master, and always have the > latest information in them. > > However, there continues to be users of older releases who still need > reference information for their configuration options. > > The toolchain used to generate the tables is able to operate on any git > repository checkout, meaning it can also generate historical tables. > > This blueprint proposes to automatically provide some form of release > information with the configuration option by comparing the options > generated from two different repositories. > > For example > * an option that appears in a Havana repository, but does not appear in > an Icehouse repository was deprecated in Havana. > * an option that does not exist in Grizzly, but appears in Havana is a > new option to Havana > > These sort of cases should then be communicated to the reader. A > selection between three potential forms for this information are envisaged: > 1. tables are updated with an additional column that provides release > information (eg "available from Icehouse onwards", "deprecated in Essex") > 2. a table of "new and removed" options between Icehouse and Juno is > added as an appendix > 3. the configuration reference is branched for the Juno release, with > different versions of the tables in each We do branch the configuration reference already, so the current version should be Icehouse only - since we haven't branched - and there's a Havana version out as well. I like your idea with "new in Icehouse" etc., still I fear the basic problem is that users look at the wrong guide. What triggered your suggestion? Do we need to say more prominently "Configuration reference for ICEHOUSE" ? Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From tom at openstack.org Fri May 2 06:51:31 2014 From: tom at openstack.org (Tom Fifield) Date: Fri, 02 May 2014 14:51:31 +0800 Subject: [Openstack-docs] Keep up the great work on the bugs :) Message-ID: <53634073.9070805@openstack.org> See attached - I just noticed that if we fix about 20 more bugs, we'll reach levels we haven't been at since July 2013. It would be amazing to see our backlog reduced to nothing so we can focus on Juno ;) Regards, Tom -------------- next part -------------- A non-text attachment was scrubbed... Name: manuals-bugs-may-2014.png Type: image/png Size: 71203 bytes Desc: not available URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140502/982b1e04/attachment-0001.png> From anne at openstack.org Fri May 2 17:53:42 2014 From: anne at openstack.org (Anne Gentle) Date: Fri, 2 May 2014 12:53:42 -0500 Subject: [Openstack-docs] Consistency for "titles" in lists? In-Reply-To: <53634329.6090206@suse.com> References: <53634329.6090206@suse.com> Message-ID: <CAD0KtVH8uxEQ4r1-qGWsiw1-JvH_NQxo3ST+h1eJg1P5SYLiVA@mail.gmail.com> I looked up Rackspace style and for a list that provides terms and more information that is not meant to be marked up as a variable list, it's: term space emdash space definition phrase period Example: - *Public* ? This setting allows any two servers with public IP addresses to be load balanced. These can be nodes outside of the Rackspace network, but if they are, standard bandwidth rates apply. I'd like to have someone at RedHat look up their style guide and let us know. Ideally we'll be able to answer these if Rackspace or RedHat gets their style guide externalized so we can look it up. Thanks, Anne On Fri, May 2, 2014 at 2:03 AM, Andreas Jaeger <aj at suse.com> wrote: > I've seen various forms used during reviews in lists with many items: > > 1) > <listitem><para><guilabel>Boot from image</guilabel>—If you choose > ... > > 2) And also: > <listitem> > <para><code>scheduler_filter_classes</code> - Specifies the list of filter > > And then the usage of > 3) <formalpara> with <title>, > > 4) ":" instead of —, > 5) &ndash or "-" > > I've seen recently some patches using the first variant but there's a lot > of variations. Do we want to have a consistent style for new changes? And > which one? > > This was triggered by reviewing https://review.openstack.org/91736, > https://review.openstack.org/90625 and then editing > config-reference/compute/section_compute-cells.xml > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140502/b442e93c/attachment.html> From anne at openstack.org Fri May 2 17:54:44 2014 From: anne at openstack.org (Anne Gentle) Date: Fri, 2 May 2014 12:54:44 -0500 Subject: [Openstack-docs] Add release version to config reference options In-Reply-To: <5363478F.5000402@suse.com> References: <5363444C.5010801@openstack.org> <5363478F.5000402@suse.com> Message-ID: <CAD0KtVGBjXGSGdU3xt-OSC+NZ4Y-jwsS_t6KRXDc1FKFW8=3QA@mail.gmail.com> On Fri, May 2, 2014 at 2:21 AM, Andreas Jaeger <aj at suse.com> wrote: > On 05/02/2014 09:07 AM, Tom Fifield wrote: > >> Hi, >> >> Related to our critical Bug #1191447: Clearly mark outdated doc pages, >> I have proposed a new blueprint for Juno >> >> "Add release version to config reference options" >> >> https://blueprints.launchpad.net/openstack-manuals/+spec/ >> add-release-version-to-config-reference-options >> >> >> The continuously published configuration reference contains tables with >> information about all configuration options in OpenStack. >> >> Currently, these tables are updated from master, and always have the >> latest information in them. >> >> However, there continues to be users of older releases who still need >> reference information for their configuration options. >> >> The toolchain used to generate the tables is able to operate on any git >> repository checkout, meaning it can also generate historical tables. >> >> This blueprint proposes to automatically provide some form of release >> information with the configuration option by comparing the options >> generated from two different repositories. >> >> For example >> * an option that appears in a Havana repository, but does not appear in >> an Icehouse repository was deprecated in Havana. >> * an option that does not exist in Grizzly, but appears in Havana is a >> new option to Havana >> >> These sort of cases should then be communicated to the reader. A >> selection between three potential forms for this information are >> envisaged: >> 1. tables are updated with an additional column that provides release >> information (eg "available from Icehouse onwards", "deprecated in Essex") >> 2. a table of "new and removed" options between Icehouse and Juno is >> added as an appendix >> 3. the configuration reference is branched for the Juno release, with >> different versions of the tables in each >> > > We do branch the configuration reference already, so the current version > should be Icehouse only - since we haven't branched - and there's a Havana > version out as well. > > I like your idea with "new in Icehouse" etc., still I fear the basic > problem is that users look at the wrong guide. What triggered your > suggestion? > > Do we need to say more prominently "Configuration reference for ICEHOUSE" ? > > Yep, as Andreas said, we do this already but just haven't yet for Icehouse. Let us know the root cause of the request. Thanks, Anne > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140502/c0e26f8e/attachment.html> From aj at suse.com Fri May 2 19:16:22 2014 From: aj at suse.com (Andreas Jaeger) Date: Fri, 02 May 2014 21:16:22 +0200 Subject: [Openstack-docs] Consistency for "titles" in lists? In-Reply-To: <CAD0KtVH8uxEQ4r1-qGWsiw1-JvH_NQxo3ST+h1eJg1P5SYLiVA@mail.gmail.com> References: <53634329.6090206@suse.com> <CAD0KtVH8uxEQ4r1-qGWsiw1-JvH_NQxo3ST+h1eJg1P5SYLiVA@mail.gmail.com> Message-ID: <5363EF06.3070705@suse.com> On 05/02/2014 07:53 PM, Anne Gentle wrote: > I looked up Rackspace style and for a list that provides terms and more > information that is not meant to be marked up as a variable list, it's: > > term space emdash space definition phrase period > > Example: > > * *Public* ? This setting allows any two servers with public IP > addresses to be load balanced. These can be nodes outside of the > Rackspace network, but if they are, standard bandwidth rates apply. > > > I'd like to have someone at RedHat look up their style guide and let us > know. For the Operations Guide, we used - as specified by O'Reilly's guide - no spaces around the emdashes. What does the Rackspace guide say about the markup for term? Is it emphasis in "bold"? > Ideally we'll be able to answer these if Rackspace or RedHat gets their > style guide externalized so we can look it up. Andreas > Thanks, > Anne > > > On Fri, May 2, 2014 at 2:03 AM, Andreas Jaeger <aj at suse.com > <mailto:aj at suse.com>> wrote: > > I've seen various forms used during reviews in lists with many items: > > 1) > <listitem><para><guilabel>Boot from image</guilabel>—If you choose > ... > > 2) And also: > <listitem> > <para><code>scheduler_filter___classes</code> - Specifies the list > of filter > > And then the usage of > 3) <formalpara> with <title>, > > 4) ":" instead of —, > 5) &ndash or "-" > > I've seen recently some patches using the first variant but there's > a lot of variations. Do we want to have a consistent style for new > changes? And which one? > > This was triggered by reviewing https://review.openstack.org/__91736 > <https://review.openstack.org/91736>, > https://review.openstack.org/__90625 > <https://review.openstack.org/90625> and then editing > config-reference/compute/__section_compute-cells.xml > > Andreas > -- > Andreas Jaeger aj@{suse.com <http://suse.com>,opensuse.org > <http://opensuse.org>} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG > N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 > A126 > > _________________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org> > http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs > <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> > > -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Fri May 2 19:24:55 2014 From: anne at openstack.org (Anne Gentle) Date: Fri, 2 May 2014 14:24:55 -0500 Subject: [Openstack-docs] Consistency for "titles" in lists? In-Reply-To: <5363EF06.3070705@suse.com> References: <53634329.6090206@suse.com> <CAD0KtVH8uxEQ4r1-qGWsiw1-JvH_NQxo3ST+h1eJg1P5SYLiVA@mail.gmail.com> <5363EF06.3070705@suse.com> Message-ID: <CAD0KtVHR-LoJPYxATWL3zNaeDONe4D-LAPRsG4+Yvt_8w=ODwA@mail.gmail.com> On Fri, May 2, 2014 at 2:16 PM, Andreas Jaeger <aj at suse.com> wrote: > On 05/02/2014 07:53 PM, Anne Gentle wrote: > >> I looked up Rackspace style and for a list that provides terms and more >> information that is not meant to be marked up as a variable list, it's: >> >> term space emdash space definition phrase period >> >> Example: >> >> * *Public* ? This setting allows any two servers with public IP >> >> addresses to be load balanced. These can be nodes outside of the >> Rackspace network, but if they are, standard bandwidth rates apply. >> >> >> I'd like to have someone at RedHat look up their style guide and let us >> know. >> > > For the Operations Guide, we used - as specified by O'Reilly's guide - no > spaces around the emdashes. > > Technical these examples ARE variable lists and O'Reilly's style wants it written as such. http://chimera.labs.oreilly.com/books/1230000000969/ch02.html#variable_list Frequently, bulleted lists should be converted to variable lists. Any bulleted list whose entries consist of a short term and its definition should be converted. For example, the following bulleted list entries: - Spellchecking: process of correcting spelling - Pagebreaking?process of breaking pages should be variable list entries: SpellcheckingProcess of correcting spelling PagebreakingProcess of breaking pages > > What does the Rackspace guide say about the markup for term? Is it > emphasis in "bold"? No additional markup for the term. > > > Ideally we'll be able to answer these if Rackspace or RedHat gets their >> style guide externalized so we can look it up. >> > > > Andreas > > Thanks, >> Anne >> >> >> On Fri, May 2, 2014 at 2:03 AM, Andreas Jaeger <aj at suse.com >> <mailto:aj at suse.com>> wrote: >> >> I've seen various forms used during reviews in lists with many items: >> >> 1) >> <listitem><para><guilabel>Boot from image</guilabel>—If you >> choose >> ... >> >> 2) And also: >> <listitem> >> <para><code>scheduler_filter___classes</code> - Specifies the list >> >> of filter >> >> And then the usage of >> 3) <formalpara> with <title>, >> >> 4) ":" instead of —, >> 5) &ndash or "-" >> >> I've seen recently some patches using the first variant but there's >> a lot of variations. Do we want to have a consistent style for new >> changes? And which one? >> >> This was triggered by reviewing https://review.openstack.org/__91736 >> <https://review.openstack.org/91736>, >> https://review.openstack.org/__90625 >> >> <https://review.openstack.org/90625> and then editing >> config-reference/compute/__section_compute-cells.xml >> >> Andreas >> -- >> Andreas Jaeger aj@{suse.com <http://suse.com>,opensuse.org >> <http://opensuse.org>} Twitter/Identica: jaegerandi >> >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany >> GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG >> N?rnberg) >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 >> A126 >> >> _________________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org> >> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__ >> openstack-docs >> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> >> >> >> > > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140502/0747ccf7/attachment-0001.html> From aj at suse.com Fri May 2 20:12:07 2014 From: aj at suse.com (Andreas Jaeger) Date: Fri, 02 May 2014 22:12:07 +0200 Subject: [Openstack-docs] Consistency for "titles" in lists? In-Reply-To: <CAD0KtVHR-LoJPYxATWL3zNaeDONe4D-LAPRsG4+Yvt_8w=ODwA@mail.gmail.com> References: <53634329.6090206@suse.com> <CAD0KtVH8uxEQ4r1-qGWsiw1-JvH_NQxo3ST+h1eJg1P5SYLiVA@mail.gmail.com> <5363EF06.3070705@suse.com> <CAD0KtVHR-LoJPYxATWL3zNaeDONe4D-LAPRsG4+Yvt_8w=ODwA@mail.gmail.com> Message-ID: <5363FC17.3080400@suse.com> On 05/02/2014 09:24 PM, Anne Gentle wrote: > > > > On Fri, May 2, 2014 at 2:16 PM, Andreas Jaeger <aj at suse.com > <mailto:aj at suse.com>> wrote: > > On 05/02/2014 07:53 PM, Anne Gentle wrote: > > I looked up Rackspace style and for a list that provides terms > and more > information that is not meant to be marked up as a variable > list, it's: > > term space emdash space definition phrase period > > Example: > > * *Public* ? This setting allows any two servers with public IP > > addresses to be load balanced. These can be nodes outside > of the > Rackspace network, but if they are, standard bandwidth > rates apply. > > > I'd like to have someone at RedHat look up their style guide and > let us > know. > > > For the Operations Guide, we used - as specified by O'Reilly's guide > - no spaces around the emdashes. > > > Technical these examples ARE variable lists and O'Reilly's style wants > it written as such. > http://chimera.labs.oreilly.com/books/1230000000969/ch02.html#variable_list I agree that they are indeed variable lists - but we haven't followed the markup usage in the manuals. I'm fine with whatever convention we agree on, my goal is to have consistency for new text and changes. > Frequently, bulleted lists should be converted to variable lists. Any > bulleted list whose entries consist of a short term and its definition > should be converted. For example, the following bulleted list entries: > > * Spellchecking: process of correcting spelling > * Pagebreaking?process of breaking pages > > should be variable list entries: > > Spellchecking > Process of correcting spelling > Pagebreaking > Process of breaking pages So, these two reviews: https://review.openstack.org/91736 https://review.openstack.org/90625 should get a -1 because of not using variable lists? Do we agree on this convention? Then I'll make it a bit clearer in the conventions wiki page and will review accordingly. > > What does the Rackspace guide say about the markup for term? Is it > emphasis in "bold"? > > > No additional markup for the term. That's different from what is used in many places in the manuals and if we go to variable lists, it is mood. thanks, Andreas > > > Ideally we'll be able to answer these if Rackspace or RedHat > gets their > style guide externalized so we can look it up. > > > > Andreas > > Thanks, > Anne > > > On Fri, May 2, 2014 at 2:03 AM, Andreas Jaeger <aj at suse.com > <mailto:aj at suse.com> > <mailto:aj at suse.com <mailto:aj at suse.com>>> wrote: > > I've seen various forms used during reviews in lists with > many items: > > 1) > <listitem><para><guilabel>Boot from > image</guilabel>—If you choose > ... > > 2) And also: > <listitem> > <para><code>scheduler_filter_____classes</code> - Specifies > the list > > of filter > > And then the usage of > 3) <formalpara> with <title>, > > 4) ":" instead of —, > 5) &ndash or "-" > > I've seen recently some patches using the first variant but > there's > a lot of variations. Do we want to have a consistent style > for new > changes? And which one? > > This was triggered by reviewing > https://review.openstack.org/____91736 > <https://review.openstack.org/__91736> > <https://review.openstack.org/__91736 > <https://review.openstack.org/91736>>, > https://review.openstack.org/____90625 > <https://review.openstack.org/__90625> > > <https://review.openstack.org/__90625 > <https://review.openstack.org/90625>> and then editing > config-reference/compute/____section_compute-cells.xml > > Andreas > -- > Andreas Jaeger aj@{suse.com <http://suse.com> > <http://suse.com>,opensuse.org <http://opensuse.org> > <http://opensuse.org>} Twitter/Identica: jaegerandi > > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, > Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG > N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A > 563C C272 > A126 > > ___________________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.__opensta__ck.org <http://openstack.org> > <mailto:Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org>> > http://lists.openstack.org/____cgi-bin/mailman/listinfo/____openstack-docs > <http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs> > > <http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs > <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs>> > > > > > -- > Andreas Jaeger aj@{suse.com <http://suse.com>,opensuse.org > <http://opensuse.org>} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG > N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 > A126 > > _________________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org> > http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs > <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> > > -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From diane.fleming at RACKSPACE.COM Fri May 2 20:19:28 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Fri, 2 May 2014 20:19:28 +0000 Subject: [Openstack-docs] Consistency for "titles" in lists? In-Reply-To: <5363FC17.3080400@suse.com> Message-ID: <CF8967B9.2C115%diane.fleming@rackspace.com> Generally, we (or at least I do) "bold" the terms in variable lists because they look a little weird without the bolding. However, someone could open a bug to make <term>xx</term> items bold by default. Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com On 5/2/14 3:12 PM, "Andreas Jaeger" <aj at suse.com> wrote: >On 05/02/2014 09:24 PM, Anne Gentle wrote: >> >> >> >> On Fri, May 2, 2014 at 2:16 PM, Andreas Jaeger <aj at suse.com >> <mailto:aj at suse.com>> wrote: >> >> On 05/02/2014 07:53 PM, Anne Gentle wrote: >> >> I looked up Rackspace style and for a list that provides terms >> and more >> information that is not meant to be marked up as a variable >> list, it's: >> >> term space emdash space definition phrase period >> >> Example: >> >> * *Public* ? This setting allows any two servers with public >>IP >> >> addresses to be load balanced. These can be nodes outside >> of the >> Rackspace network, but if they are, standard bandwidth >> rates apply. >> >> >> I'd like to have someone at RedHat look up their style guide and >> let us >> know. >> >> >> For the Operations Guide, we used - as specified by O'Reilly's guide >> - no spaces around the emdashes. >> >> >> Technical these examples ARE variable lists and O'Reilly's style wants >> it written as such. >> >>http://chimera.labs.oreilly.com/books/1230000000969/ch02.html#variable_li >>st > >I agree that they are indeed variable lists - but we haven't followed >the markup usage in the manuals. > >I'm fine with whatever convention we agree on, my goal is to have >consistency for new text and changes. > >> Frequently, bulleted lists should be converted to variable lists. Any >> bulleted list whose entries consist of a short term and its definition >> should be converted. For example, the following bulleted list entries: >> >> * Spellchecking: process of correcting spelling >> * Pagebreaking?process of breaking pages >> >> should be variable list entries: >> >> Spellchecking >> Process of correcting spelling >> Pagebreaking >> Process of breaking pages > >So, these two reviews: >https://review.openstack.org/91736 >https://review.openstack.org/90625 > >should get a -1 because of not using variable lists? > >Do we agree on this convention? Then I'll make it a bit clearer in the >conventions wiki page and will review accordingly. > >> >> What does the Rackspace guide say about the markup for term? Is it >> emphasis in "bold"? >> >> >> No additional markup for the term. > >That's different from what is used in many places in the manuals and if >we go to variable lists, it is mood. > >thanks, >Andreas > >> >> >> Ideally we'll be able to answer these if Rackspace or RedHat >> gets their >> style guide externalized so we can look it up. >> >> >> >> Andreas >> >> Thanks, >> Anne >> >> >> On Fri, May 2, 2014 at 2:03 AM, Andreas Jaeger <aj at suse.com >> <mailto:aj at suse.com> >> <mailto:aj at suse.com <mailto:aj at suse.com>>> wrote: >> >> I've seen various forms used during reviews in lists with >> many items: >> >> 1) >> <listitem><para><guilabel>Boot from >> image</guilabel>—If you choose >> ... >> >> 2) And also: >> <listitem> >> <para><code>scheduler_filter_____classes</code> - Specifies >> the list >> >> of filter >> >> And then the usage of >> 3) <formalpara> with <title>, >> >> 4) ":" instead of —, >> 5) &ndash or "-" >> >> I've seen recently some patches using the first variant but >> there's >> a lot of variations. Do we want to have a consistent style >> for new >> changes? And which one? >> >> This was triggered by reviewing >> https://review.openstack.org/____91736 >> <https://review.openstack.org/__91736> >> <https://review.openstack.org/__91736 >> <https://review.openstack.org/91736>>, >> https://review.openstack.org/____90625 >> <https://review.openstack.org/__90625> >> >> <https://review.openstack.org/__90625 >> <https://review.openstack.org/90625>> and then editing >> config-reference/compute/____section_compute-cells.xml >> >> Andreas >> -- >> Andreas Jaeger aj@{suse.com <http://suse.com> >> <http://suse.com>,opensuse.org <http://opensuse.org> >> <http://opensuse.org>} Twitter/Identica: jaegerandi >> >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, >> Germany >> GF: Jeff Hawn,Jennifer Guild,Felix >>Imend?rffer,HRB16746 (AG >> N?rnberg) >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A >> 563C C272 >> A126 >> >> ___________________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.__opensta__ck.org >><http://openstack.org> >> <mailto:Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org>> >> >>http://lists.openstack.org/____cgi-bin/mailman/listinfo/____openstack-doc >>s >> >><http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs> >> >> >><http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs >> >><http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs>> >> >> >> >> >> -- >> Andreas Jaeger aj@{suse.com <http://suse.com>,opensuse.org >> <http://opensuse.org>} Twitter/Identica: jaegerandi >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany >> GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG >> N?rnberg) >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 >> A126 >> >> _________________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org> >> >>http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs >> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> >> >> > > >-- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > >_______________________________________________ >Openstack-docs mailing list >Openstack-docs at lists.openstack.org >http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs From shaunm at gnome.org Sat May 3 12:53:02 2014 From: shaunm at gnome.org (Shaun McCance) Date: Sat, 03 May 2014 07:53:02 -0500 Subject: [Openstack-docs] Switch to itstool for docs translation? Message-ID: <1399121582.24585.10.camel@verso> Hi all, I've been working on switching the docs translation infrastructure over to itstool. This affects openstack-manuals, operations-guide, and api-site. The current tools are based on xml2po, but they don't call xml2po directly. Instead, they import xml2po and mess around with its internals to get some custom behavior. itstool is designed to handle custom behavior with rules from the W3C Internationalization Tag Set (ITS). You can see the ITS I put together so far here: https://review.openstack.org/#/c/91869/3/os_doc_tools/resources/openstack.its,unified Using ITS also allows us to do local ITS attributes to override the behavior for specific elements. See a simple example here: https://review.openstack.org/#/c/91872/1/api-quick-start/src/docbkx/api-quick-start-intro.xml,unified Most messages in the PO files will be the same. The one big difference will be in how placeholders are done when there's a block-level element inside a block-level element (a practice I discourage anyway). Blueprint and some patches: https://blueprints.launchpad.net/openstack-manuals/+spec/itstool-for-docs https://review.openstack.org/#/q/topic:bp/itstool-for-docs,n,z I'd like to get input from translators, as well as any other docs folks who've worked on this. Most of the document translations are incomplete anyway, but it would nevertheless be best to do this at the beginning of a release cycle. -- Shaun From aj at suse.com Sat May 3 16:03:07 2014 From: aj at suse.com (Andreas Jaeger) Date: Sat, 03 May 2014 18:03:07 +0200 Subject: [Openstack-docs] time to Branch for icehouse? Message-ID: <5365133B.3010400@suse.com> Having looked at the open bugs and the reviews of the last days, it seems we've done a great job with Install Guide and Config Reference and we can safely branch now. What do you think? Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From sgordon at redhat.com Sat May 3 17:36:21 2014 From: sgordon at redhat.com (Steve Gordon) Date: Sat, 3 May 2014 13:36:21 -0400 (EDT) Subject: [Openstack-docs] time to Branch for icehouse? In-Reply-To: <5365133B.3010400@suse.com> References: <5365133B.3010400@suse.com> Message-ID: <774235864.66768.1399138581471.JavaMail.zimbra@redhat.com> ----- Original Message ----- > Having looked at the open bugs and the reviews of the last days, it > seems we've done a great job with Install Guide and Config Reference and > we can safely branch now. > > What do you think? > > Andreas +1 from me. -Steve From anne at openstack.org Sat May 3 20:49:19 2014 From: anne at openstack.org (Anne Gentle) Date: Sat, 3 May 2014 15:49:19 -0500 Subject: [Openstack-docs] time to Branch for icehouse? In-Reply-To: <5365133B.3010400@suse.com> References: <5365133B.3010400@suse.com> Message-ID: <CAD0KtVERMv0_67M2Z+kaxyK5OpO-okkFs=ZgGe8whSzbJRCt=Q@mail.gmail.com> On Sat, May 3, 2014 at 11:03 AM, Andreas Jaeger <aj at suse.com> wrote: > Having looked at the open bugs and the reviews of the last days, it seems > we've done a great job with Install Guide and Config Reference and we can > safely branch now. > > What do you think? I'm up for it. Or I'm down with that. Whichever. :) > > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140503/3f356211/attachment.html> From mkassawara at gmail.com Sat May 3 23:01:07 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Sat, 3 May 2014 17:01:07 -0600 Subject: [Openstack-docs] time to Branch for icehouse? In-Reply-To: <CAD0KtVERMv0_67M2Z+kaxyK5OpO-okkFs=ZgGe8whSzbJRCt=Q@mail.gmail.com> References: <5365133B.3010400@suse.com> <CAD0KtVERMv0_67M2Z+kaxyK5OpO-okkFs=ZgGe8whSzbJRCt=Q@mail.gmail.com> Message-ID: <CABA+jQpFOBKsXz8p6iXiDAmDq4Vx+A1jN22DR3a=hZtZHZoGOw@mail.gmail.com> Go for it! On Sat, May 3, 2014 at 2:49 PM, Anne Gentle <anne at openstack.org> wrote: > > > > On Sat, May 3, 2014 at 11:03 AM, Andreas Jaeger <aj at suse.com> wrote: > >> Having looked at the open bugs and the reviews of the last days, it seems >> we've done a great job with Install Guide and Config Reference and we can >> safely branch now. >> >> What do you think? > > > > I'm up for it. Or I'm down with that. Whichever. :) > > >> >> >> Andreas >> -- >> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany >> GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140503/8396651f/attachment.html> From aj at suse.com Sun May 4 00:13:02 2014 From: aj at suse.com (Andreas Jaeger) Date: Sun, 04 May 2014 02:13:02 +0200 Subject: [Openstack-docs] time to Branch for icehouse? In-Reply-To: <CAD0KtVERMv0_67M2Z+kaxyK5OpO-okkFs=ZgGe8whSzbJRCt=Q@mail.gmail.com> References: <5365133B.3010400@suse.com> <CAD0KtVERMv0_67M2Z+kaxyK5OpO-okkFs=ZgGe8whSzbJRCt=Q@mail.gmail.com> Message-ID: <5365860E.7020506@suse.com> On 05/03/2014 10:49 PM, Anne Gentle wrote: > > > > On Sat, May 3, 2014 at 11:03 AM, Andreas Jaeger <aj at suse.com > <mailto:aj at suse.com>> wrote: > > Having looked at the open bugs and the reviews of the last days, it > seems we've done a great job with Install Guide and Config Reference > and we can safely branch now. > > What do you think? > > > > I'm up for it. Or I'm down with that. Whichever. :) Before we branch, please include this patch so that publishing is not done to both trunk and icehouse anymore: https://review.openstack.org/91971 Once we have branched, we should change the publishdocs section on the stable/icehouse branch to just: commands = openstack-doc-test --check-build --publish --only-book install-guide --only-book config-reference This is the same what we do on stable/havana, Andreas > > > Andreas > -- > Andreas Jaeger aj@{suse.com <http://suse.com>,opensuse.org > <http://opensuse.org>} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG > N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 > A126 > > _________________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org> > http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs > <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> > > > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Sun May 4 11:33:29 2014 From: aj at suse.com (Andreas Jaeger) Date: Sun, 04 May 2014 13:33:29 +0200 Subject: [Openstack-docs] [Openstack-i18n] Switch to itstool for docs translation? In-Reply-To: <1399121582.24585.10.camel@verso> References: <1399121582.24585.10.camel@verso> Message-ID: <53662589.2090504@suse.com> On 05/03/2014 02:53 PM, Shaun McCance wrote: > Hi all, > > I've been working on switching the docs translation infrastructure over > to itstool. This affects openstack-manuals, operations-guide, and > api-site. The current tools are based on xml2po, but they don't call > xml2po directly. Instead, they import xml2po and mess around with its > internals to get some custom behavior. > > itstool is designed to handle custom behavior with rules from the W3C > Internationalization Tag Set (ITS). You can see the ITS I put together > so far here: > > https://review.openstack.org/#/c/91869/3/os_doc_tools/resources/openstack.its,unified > > Using ITS also allows us to do local ITS attributes to override the > behavior for specific elements. See a simple example here: > > https://review.openstack.org/#/c/91872/1/api-quick-start/src/docbkx/api-quick-start-intro.xml,unified > > Most messages in the PO files will be the same. The one big difference > will be in how placeholders are done when there's a block-level element > inside a block-level element (a practice I discourage anyway). Could you give an example, please? > Blueprint and some patches: > > https://blueprints.launchpad.net/openstack-manuals/+spec/itstool-for-docs > https://review.openstack.org/#/q/topic:bp/itstool-for-docs,n,z Looking at the patches, I really like what I see and would love to see us move forward. This needs also some documentation in the OpenStack wiki on the recommend usage of local ITS attributes like its:translate and its:withinText. > I'd like to get input from translators, as well as any other docs folks > who've worked on this. Most of the document translations are incomplete > anyway, but it would nevertheless be best to do this at the beginning of > a release cycle. I assume that we can convert the existing translated files in such a way that we do not loose translations? How to do this properly? Download current files from transifex, convert into new format, upload converted files - and then continue translating? Or will it be enough to upload the pot file and let transfix do the translation? Did you test a conversation of locale files and reconstructed translated manuals? Is this just working with the updated tools or are additional steps needed? I think we need to ensure with the infra team that itstools are installed on our machines. I see that some patches are dependent on each other and we need to do certain steps in a specific order. Is this something you can write down as plan, please? Thanks! Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From slong at redhat.com Mon May 5 00:59:49 2014 From: slong at redhat.com (Summer Long) Date: Sun, 4 May 2014 20:59:49 -0400 (EDT) Subject: [Openstack-docs] time to Branch for icehouse? In-Reply-To: <5365860E.7020506@suse.com> References: <5365133B.3010400@suse.com> <CAD0KtVERMv0_67M2Z+kaxyK5OpO-okkFs=ZgGe8whSzbJRCt=Q@mail.gmail.com> <5365860E.7020506@suse.com> Message-ID: <1879856974.225639.1399251589083.JavaMail.zimbra@redhat.com> Have a couple of patches on review I'd like to include first? Got caught out by the 'term=value' spacing issue. -- Summer Long OpenStack Documentation Lead Engineering Content Services Red Hat Asia Pacific Brisbane, Australia slong at redhat.com | irc: slong ----- Original Message ----- > From: "Andreas Jaeger" <aj at suse.com> > To: "Anne Gentle" <anne at openstack.org> > Cc: openstack-docs at lists.openstack.org > Sent: Sunday, May 4, 2014 10:13:02 AM > Subject: Re: [Openstack-docs] time to Branch for icehouse? > > On 05/03/2014 10:49 PM, Anne Gentle wrote: > > > > > > > > On Sat, May 3, 2014 at 11:03 AM, Andreas Jaeger <aj at suse.com > > <mailto:aj at suse.com>> wrote: > > > > Having looked at the open bugs and the reviews of the last days, it > > seems we've done a great job with Install Guide and Config Reference > > and we can safely branch now. > > > > What do you think? > > > > > > > > I'm up for it. Or I'm down with that. Whichever. :) > > Before we branch, please include this patch so that publishing > is not done to both trunk and icehouse anymore: > https://review.openstack.org/91971 > > Once we have branched, we should change the publishdocs > section on the stable/icehouse branch to just: > commands = > openstack-doc-test --check-build --publish --only-book install-guide > --only-book config-reference > > This is the same what we do on stable/havana, > > Andreas > > > > > > > Andreas > > -- > > Andreas Jaeger aj@{suse.com <http://suse.com>,opensuse.org > > <http://opensuse.org>} Twitter/Identica: jaegerandi > > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG > > N?rnberg) > > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 > > A126 > > > > _________________________________________________ > > Openstack-docs mailing list > > Openstack-docs at lists.__openstack.org > > <mailto:Openstack-docs at lists.openstack.org> > > http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs > > <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> > > > > > > > > > > _______________________________________________ > > Openstack-docs mailing list > > Openstack-docs at lists.openstack.org > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > > > > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > From aj at suse.com Mon May 5 04:35:19 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 05 May 2014 06:35:19 +0200 Subject: [Openstack-docs] time to Branch for icehouse? In-Reply-To: <1879856974.225639.1399251589083.JavaMail.zimbra@redhat.com> References: <5365133B.3010400@suse.com> <CAD0KtVERMv0_67M2Z+kaxyK5OpO-okkFs=ZgGe8whSzbJRCt=Q@mail.gmail.com> <5365860E.7020506@suse.com> <1879856974.225639.1399251589083.JavaMail.zimbra@redhat.com> Message-ID: <53671507.1040906@suse.com> On 05/05/2014 02:59 AM, Summer Long wrote: > Have a couple of patches on review I'd like to include first? Got caught out by the 'term=value' spacing issue. > We can backport as usual ;) But yeah, let's see what we can get reviewed quickly, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From berendt at b1-systems.de Mon May 5 09:27:39 2014 From: berendt at b1-systems.de (Christian Berendt) Date: Mon, 05 May 2014 11:27:39 +0200 Subject: [Openstack-docs] [cli-reference] change "command client client" to "command line interface"? Message-ID: <5367598B.5010306@b1-systems.de> The name of the cli-reference is "OpenStack Command-Line Interface Reference". Inside the document we're always using "xyz command-line client(s)". Should we rename the document to "OpenStack Command-Line Client Reference" or should we rename all occurrences of "command-line client" to "command-line interface"? Christian. -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 From berendt at b1-systems.de Mon May 5 10:09:45 2014 From: berendt at b1-systems.de (Christian Berendt) Date: Mon, 05 May 2014 12:09:45 +0200 Subject: [Openstack-docs] How to fix typos in pot files? Message-ID: <53676369.1090303@b1-systems.de> I found a little typo in two pot files. common/locale/common.pot install-guide/locale/install-guide.pot How can I fix those files? Can I modify them in-tree? Christian. -- Christian Berendt Cloud Computing Solution Architect Tel.: +49-171-5542175 Mail: berendt at b1-systems.de B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 From aj at suse.com Mon May 5 11:06:46 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 05 May 2014 13:06:46 +0200 Subject: [Openstack-docs] How to fix typos in pot files? In-Reply-To: <53676369.1090303@b1-systems.de> References: <53676369.1090303@b1-systems.de> Message-ID: <536770C6.1010907@suse.com> On 05/05/2014 12:09 PM, Christian Berendt wrote: > I found a little typo in two pot files. > > common/locale/common.pot > install-guide/locale/install-guide.pot They are regenerated automatically every morning. Just fix the sources which are wrong. > How can I fix those files? Can I modify them in-tree? Please don't, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From diane.fleming at RACKSPACE.COM Mon May 5 13:33:24 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Mon, 5 May 2014 13:33:24 +0000 Subject: [Openstack-docs] [cli-reference] change "command client client" to "command line interface"? In-Reply-To: <5367598B.5010306@b1-systems.de> References: <5367598B.5010306@b1-systems.de> Message-ID: <DA2F3C02-13D4-46FE-8414-A8C8E9CE32FC@RACKSPACE.COM> Yes, there is a bit of disconnect there. The acronym CLI stands for command-line interface, but the actual python packages are referred to as "clients." My preference would be to rename the book "OpenStack Command Reference" and title each chapter in the book, "Xxx commands" (like Block Storage commands). Then, in the overview section, we can say that users can run commands from the command line or include them in scripts by installing clients. I see no reason for including the word "interface" or "client" in the title or chapter titles. Sent from my iPhone > On May 5, 2014, at 2:30 AM, "Christian Berendt" <berendt at b1-systems.de> wrote: > > The name of the cli-reference is "OpenStack Command-Line Interface Reference". Inside the document we're always using "xyz command-line client(s)". > > Should we rename the document to "OpenStack Command-Line Client Reference" or should we rename all occurrences of "command-line client" to "command-line interface"? > > Christian. > > -- > Christian Berendt > Cloud Computing Solution Architect > Mail: berendt at b1-systems.de > > B1 Systems GmbH > Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de > GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs From eperdomo at cisco.com Mon May 5 18:40:20 2014 From: eperdomo at cisco.com (Edgar Magana Perdomo (eperdomo)) Date: Mon, 5 May 2014 18:40:20 +0000 Subject: [Openstack-docs] time to Branch for icehouse? In-Reply-To: <53671507.1040906@suse.com> References: <5365133B.3010400@suse.com> <CAD0KtVERMv0_67M2Z+kaxyK5OpO-okkFs=ZgGe8whSzbJRCt=Q@mail.gmail.com> <5365860E.7020506@suse.com> <1879856974.225639.1399251589083.JavaMail.zimbra@redhat.com> <53671507.1040906@suse.com> Message-ID: <CF8D2919.FA54%eperdomo@cisco.com> Great Job on the Docs Folks! Edgar On 5/4/14, 9:35 PM, "Andreas Jaeger" <aj at suse.com> wrote: >On 05/05/2014 02:59 AM, Summer Long wrote: >> Have a couple of patches on review I'd like to include first? Got >>caught out by the 'term=value' spacing issue. >> > >We can backport as usual ;) > >But yeah, let's see what we can get reviewed quickly, > >Andreas >-- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > >_______________________________________________ >Openstack-docs mailing list >Openstack-docs at lists.openstack.org >http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs From aj at suse.com Mon May 5 18:40:48 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 05 May 2014 20:40:48 +0200 Subject: [Openstack-docs] Consistency for "titles" in lists? In-Reply-To: <CF8967B9.2C115%diane.fleming@rackspace.com> References: <CF8967B9.2C115%diane.fleming@rackspace.com> Message-ID: <5367DB30.7070903@suse.com> On 05/02/2014 10:19 PM, Diane Fleming wrote: > Generally, we (or at least I do) "bold" the terms in variable lists > because they look a little weird without the bolding. > > However, someone could open a bug to make <term>xx</term> items bold by > default. So, what about the following proposal: 1) File a bug against our tools asking David Cramer to mark <term> as bold in variable lists. 2) Add to conventions (with proper markup examples, enhancing current entry about variable list): For lists that consist of a short term and its definition, variable lists should be used. Any current usage as bulleted list should be converted. For example, the following bulleted list entries: Spellchecking: process of correcting spelling Pagebreaking?process of breaking pages should be variable list entries: Spellchecking Process of correcting spelling Pagebreaking Process of breaking pages Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From diane.fleming at RACKSPACE.COM Mon May 5 19:01:14 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Mon, 5 May 2014 19:01:14 +0000 Subject: [Openstack-docs] Consistency for "titles" in lists? In-Reply-To: <5367DB30.7070903@suse.com> Message-ID: <CF8D2E03.2C40A%diane.fleming@rackspace.com> +1 Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com On 5/5/14 11:40 AM, "Andreas Jaeger" <aj at suse.com> wrote: >On 05/02/2014 10:19 PM, Diane Fleming wrote: >> Generally, we (or at least I do) "bold" the terms in variable lists >> because they look a little weird without the bolding. >> >> However, someone could open a bug to make <term>xx</term> items bold by >> default. > >So, what about the following proposal: > >1) File a bug against our tools asking David Cramer to mark <term> as >bold in variable lists. > >2) Add to conventions (with proper markup examples, enhancing current >entry about variable list): > >For lists that consist of a short term and its definition, variable >lists should be used. > >Any current usage as bulleted list should be converted. For example, the >following bulleted list entries: > > Spellchecking: process of correcting spelling > Pagebreaking?process of breaking pages > >should be variable list entries: > >Spellchecking > Process of correcting spelling >Pagebreaking > Process of breaking pages > >Andreas >-- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From slong at redhat.com Mon May 5 20:08:12 2014 From: slong at redhat.com (Summer Long) Date: Mon, 5 May 2014 16:08:12 -0400 (EDT) Subject: [Openstack-docs] Consistency for "titles" in lists? In-Reply-To: <CF8D2E03.2C40A%diane.fleming@rackspace.com> References: <CF8D2E03.2C40A%diane.fleming@rackspace.com> Message-ID: <635429448.1429695.1399320492199.JavaMail.zimbra@redhat.com> +1 cheers, Summer -- Summer Long OpenStack Documentation Lead Engineering Content Services Red Hat Asia Pacific Brisbane, Australia slong at redhat.com | irc: slong ----- Original Message ----- > From: "Diane Fleming" <diane.fleming at RACKSPACE.COM> > To: "Andreas Jaeger" <aj at suse.com>, "Anne Gentle" <anne at openstack.org> > Cc: openstack-docs at lists.openstack.org > Sent: Tuesday, May 6, 2014 5:01:14 AM > Subject: Re: [Openstack-docs] Consistency for "titles" in lists? > > +1 > Diane > ---------------------------------------------- > Diane Fleming > Software Developer II - US > > diane.fleming at rackspace.com > Cell 512.323.6799 > Office 512.874.1260 > Skype drfleming0227 > Google-plus diane.fleming at gmail.com > > > > > > > On 5/5/14 11:40 AM, "Andreas Jaeger" <aj at suse.com> wrote: > > >On 05/02/2014 10:19 PM, Diane Fleming wrote: > >> Generally, we (or at least I do) "bold" the terms in variable lists > >> because they look a little weird without the bolding. > >> > >> However, someone could open a bug to make <term>xx</term> items bold by > >> default. > > > >So, what about the following proposal: > > > >1) File a bug against our tools asking David Cramer to mark <term> as > >bold in variable lists. > > > >2) Add to conventions (with proper markup examples, enhancing current > >entry about variable list): > > > >For lists that consist of a short term and its definition, variable > >lists should be used. > > > >Any current usage as bulleted list should be converted. For example, the > >following bulleted list entries: > > > > Spellchecking: process of correcting spelling > > Pagebreaking?process of breaking pages > > > >should be variable list entries: > > > >Spellchecking > > Process of correcting spelling > >Pagebreaking > > Process of breaking pages > > > >Andreas > >-- > > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > From anne at openstack.org Mon May 5 21:28:48 2014 From: anne at openstack.org (Anne Gentle) Date: Mon, 5 May 2014 16:28:48 -0500 Subject: [Openstack-docs] Consistency for "titles" in lists? In-Reply-To: <5367DB30.7070903@suse.com> References: <CF8967B9.2C115%diane.fleming@rackspace.com> <5367DB30.7070903@suse.com> Message-ID: <CAD0KtVF70t7LpWJ8sRqU39q8RCkkFyyjwgfTE2R=KhsPhMuCQQ@mail.gmail.com> Sounds good to me. I'd log the bug myself but I'm at Write the Docs and the network is a little slow. On Mon, May 5, 2014 at 1:40 PM, Andreas Jaeger <aj at suse.com> wrote: > On 05/02/2014 10:19 PM, Diane Fleming wrote: > >> Generally, we (or at least I do) "bold" the terms in variable lists >> because they look a little weird without the bolding. >> >> However, someone could open a bug to make <term>xx</term> items bold by >> default. >> > > So, what about the following proposal: > > 1) File a bug against our tools asking David Cramer to mark <term> as bold > in variable lists. > > 2) Add to conventions (with proper markup examples, enhancing current > entry about variable list): > > For lists that consist of a short term and its definition, variable lists > should be used. > > Any current usage as bulleted list should be converted. For example, the > following bulleted list entries: > > > Spellchecking: process of correcting spelling > Pagebreaking?process of breaking pages > > should be variable list entries: > > Spellchecking > Process of correcting spelling > Pagebreaking > Process of breaking pages > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140505/6969d597/attachment.html> From aj at suse.com Tue May 6 19:53:03 2014 From: aj at suse.com (Andreas Jaeger) Date: Tue, 06 May 2014 21:53:03 +0200 Subject: [Openstack-docs] Consistency for "titles" in lists? In-Reply-To: <CF8D2E03.2C40A%diane.fleming@rackspace.com> References: <CF8D2E03.2C40A%diane.fleming@rackspace.com> Message-ID: <53693D9F.2050209@suse.com> I've updated the already great convention - that I apparently overlooked - with the examples given: https://wiki.openstack.org/wiki/Documentation/Conventions#Term.2Fdescription_or_key.2Fvalue_pairs And filled this bug: https://bugs.launchpad.net/openstack-manuals/+bug/1316770 Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From slong at redhat.com Wed May 7 11:57:12 2014 From: slong at redhat.com (Summer Long) Date: Wed, 7 May 2014 07:57:12 -0400 (EDT) Subject: [Openstack-docs] time to Branch for icehouse? In-Reply-To: <53671507.1040906@suse.com> References: <5365133B.3010400@suse.com> <CAD0KtVERMv0_67M2Z+kaxyK5OpO-okkFs=ZgGe8whSzbJRCt=Q@mail.gmail.com> <5365860E.7020506@suse.com> <1879856974.225639.1399251589083.JavaMail.zimbra@redhat.com> <53671507.1040906@suse.com> Message-ID: <718121345.3429152.1399463832116.JavaMail.zimbra@redhat.com> Apologies, have stalled out on bugs, but am not sure on timing anyway. Andreas, did you already branch the Config Ref? thanks, Summer -- Summer Long OpenStack Documentation Lead Engineering Content Services Red Hat Asia Pacific Brisbane, Australia slong at redhat.com | irc: slong ----- Original Message ----- > From: "Andreas Jaeger" <aj at suse.com> > To: "Summer Long" <slong at redhat.com> > Cc: "Anne Gentle" <anne at openstack.org>, openstack-docs at lists.openstack.org > Sent: Monday, May 5, 2014 2:35:19 PM > Subject: Re: [Openstack-docs] time to Branch for icehouse? > > On 05/05/2014 02:59 AM, Summer Long wrote: > > Have a couple of patches on review I'd like to include first? Got caught > > out by the 'term=value' spacing issue. > > > > We can backport as usual ;) > > But yeah, let's see what we can get reviewed quickly, > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > From aj at suse.com Wed May 7 12:34:25 2014 From: aj at suse.com (Andreas Jaeger) Date: Wed, 07 May 2014 14:34:25 +0200 Subject: [Openstack-docs] time to Branch for icehouse? In-Reply-To: <718121345.3429152.1399463832116.JavaMail.zimbra@redhat.com> References: <5365133B.3010400@suse.com> <CAD0KtVERMv0_67M2Z+kaxyK5OpO-okkFs=ZgGe8whSzbJRCt=Q@mail.gmail.com> <5365860E.7020506@suse.com> <1879856974.225639.1399251589083.JavaMail.zimbra@redhat.com> <53671507.1040906@suse.com> <718121345.3429152.1399463832116.JavaMail.zimbra@redhat.com> Message-ID: <536A2851.6040602@suse.com> On 05/07/2014 01:57 PM, Summer Long wrote: > Apologies, have stalled out on bugs, but am not sure on timing anyway. > Andreas, did you already branch the Config Ref? Anne needs to branch - and this has not happened yet, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Wed May 7 16:16:48 2014 From: anne at openstack.org (Anne Gentle) Date: Wed, 7 May 2014 09:16:48 -0700 Subject: [Openstack-docs] =?utf-8?b?W0RvY10gW2NlaWxvbWV0ZXJdIFtjaW5kZXJd?= =?utf-8?b?IFtnbGFuY2VdIFtoZWF0XSBbaG9yaXpvbl0gW2tleXN0b25lXSBbbmV1?= =?utf-8?q?tron=5D_=5Bnova=5D_=5Bswift=5D_=5Btrove=5D_Atlanta_Summi?= =?utf-8?q?t_=E2=80=93_Discuss_docs_process_and_tool_improvements?= Message-ID: <CAD0KtVGzg367fV8QjvBUA5GXjaa4vcri2B0TB00AhiyaUmGdaA@mail.gmail.com> Hi all, Anne here - your friendly documentarian! As the docs PTL, it?s my job to gather input about and make doc tool and process decisions. This note is the first step: Your responses to this note give me input to share at the Summit where, hopefully, we will form a consensus about process and tool changes. About a week after the Summit, I'll produce a roadmap for changes that we will implement as a community. A recurring issue that I hope we can solve is barriers to doc contributions. Leading up to the Summit, I've gathered as much data as I can about these barriers. We have an awesome doc team and 20 core people on the team, but only about dozen people write and review the bulk of the cross-project documentation regularly. It's amazing we've accomplished all we have with the resources available. We have increased doc contributions by 10% since the last release, but even so, we must find ways to increase the doc contributor base. Remember three and a half years ago? We had nova and swift and a web site for each. Fast-forward and we now have docs for multiple audiences: - Contributors who make OpenStack - Deployers who configure OpenStack - Operations pros that run OpenStack - End users who consume and administer OpenStack But the docs? contributor base is not growing at the same rate as our audiences. Why not? The responses to my recent survey about doc contributions indicate that the top barriers to docs? contributions are: - Tools: DocBook and WADL are difficult - Doc locations: Lack of knowledge about where docs belong - Process: Git/gerrit as process - Subject-matter expertise: People do not have test environments and they feel that they don't know enough to contribute. Also, 70% of the respondents to the survey work on or consume OpenStack fewer than 10 hours a week. It's not easy to interpret and analyze this data, but I believe we're not facilitating part-time OpenStack users to write docs and feel confident in their contributions. To solve this problem, I want to explore possible changes to our doc tools and processes. We must engage more doc contributors to spread the doc creation and maintenance burden. Tuesday at 12:05 in B304, [1] we're having cross-project documentation session to discuss this list of requirements for doc tools and process changes: (See [2] for spreadsheet format.) Experience: Solution must be completely open source Content must be available online Search engines must be able to index Content must be searchable Content should be easily cross-linked by topic and type (priority: low) Enable comments, ratings, and analytics (or ask.openstack.org integration) (priority: low) Distribution: Readers must get versions of technical content specific to version of product Modular authoring of content Graphic and text content should be stored as files, not in a database Consumers must get technical content in PDF, html, video, and audio Workflow for review and approval prior to publishing content Authoring: Content must be re-usable across authors and personas (Single source) Must support many content authors with multiple authoring tools Existing content must migrate smoothly All content versions need to be comparable (diff) across versions Content must be organizationally segregated based on user personas Draft content must be reviewable in HTML Link maintenance - Links must update with little manual maintenance to avoid broken links and link validation I want to gather input about these requirements before we discuss implementation. As far as tools go, some possible solutions are Markdown, reStructuredText (RST), AsciiDoc, each with its own build framework. I'm not anticipating a complete migration, but we need to solve these barriers for certain docs. Please let me know your thoughts through the OpenStack-docs mailing list if you cannot attend in person. I am excited to hear your ideas, and I can't wait to meet a wider audience and serve more doc contributors. Thanks, Anne [1] http://junodesignsummit.sched.org/event/626a1e21babaf30d98973f5eb7402fcf [2] https://docs.google.com/spreadsheet/ccc?key=0AhXvn1h0dcyYdFNaQW1OaVNNejZzYlRMZjBnT0pLMVE&usp=sharing -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140507/99cf8a34/attachment.html> From mkassawara at gmail.com Wed May 7 19:15:42 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Wed, 7 May 2014 13:15:42 -0600 Subject: [Openstack-docs] =?utf-8?q?Atlanta_Summit_=E2=80=93_Patching_the_?= =?utf-8?q?documentation_process?= Message-ID: <CABA+jQpPPeiX0+_3kGPE1qE2YwCG=sMYf9OVe2+p1Bp42=dRgg@mail.gmail.com> On Thursday morning at 9:50 in room B301, we're holding a session [1] on how to improve the documentation process which includes the following topics: - Discuss creation of a new wiki page for documentation review guidelines and review the associated draft [2] - Discuss how to improve the new documentation contributors wiki page [3][4] - Discuss use of the installation guide as the standard for configurations, labels, etc. - Discuss use of an online style guide beyond our conventions - Discuss the discipline of submitting a bug and waiting for confirmation/triage/discussion/prioritization before uploading a patch Please refer to the associated Etherpad [5] for more details. [1] http://sched.co/1ik80Gn [2] https://wiki.openstack.org/wiki/Documentation/ReviewGuidelines [3] https://wiki.openstack.org/wiki/Documentation/HowTo<http://wiki.openstack.org/wiki/Documentation/HowTo/> [4] https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers [5] https://etherpad.openstack.org/p/summit0514-session-patching-the-docs-process Looking forward to seeing everyone at the summit! Matt -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140507/c15574f2/attachment.html> From rl at patchworkscience.org Wed May 7 20:43:38 2014 From: rl at patchworkscience.org (Roger Luethi) Date: Wed, 7 May 2014 22:43:38 +0200 Subject: [Openstack-docs] =?utf-8?b?W0RvY10gW2NlaWxvbWV0ZXJdIFtjaW5kZXJd?= =?utf-8?b?IFtnbGFuY2VdIFtoZWF0XSBbaG9yaXpvbl0gW2tleXN0b25lXSBbbmV1dHJv?= =?utf-8?b?bl0gW25vdmFdIFtzd2lmdF0gW3Ryb3ZlXSBBdGxhbnRhIFN1bW1pdCDigJMg?= =?utf-8?q?Discuss_docs_process_and_tool_improvements?= In-Reply-To: <CAD0KtVGzg367fV8QjvBUA5GXjaa4vcri2B0TB00AhiyaUmGdaA@mail.gmail.com> References: <CAD0KtVGzg367fV8QjvBUA5GXjaa4vcri2B0TB00AhiyaUmGdaA@mail.gmail.com> Message-ID: <20140507204338.GA22118@hellgate.ch> On Wed, 07 May 2014 09:16:48 -0700, Anne Gentle wrote: > Why not? The responses to my recent survey about doc contributions indicate > that the top barriers to docs? contributions are: > > - Tools: DocBook and WADL are difficult DocBook may be a pain to set up, but editing DocBook documents is hardly more difficult than Markdown, RST or any other solution will be by the time you have added all the features you want to have. Formatting docs is hard because the style guides demand that numerous rules be considered. Ditching DocBook won't change that. > - Subject-matter expertise: People do not have test environments and they > feel that they don't know enough to contribute. Also, 70% of the > respondents to the survey work on or consume OpenStack fewer than 10 hours > a week. The people who are qualified to contribute to the docs are usually not non-technical people, but they can't spend hours setting up an environment just to work on docs. IMHO good documentation (or scripts, or VM downloads) that make it easy to create a complete, working environment for testing and building documentation would go a long way towards making contributions easier. Roger From berendt at b1-systems.de Thu May 8 16:06:34 2014 From: berendt at b1-systems.de (Christian Berendt) Date: Thu, 08 May 2014 18:06:34 +0200 Subject: [Openstack-docs] =?utf-8?b?W0RvY10gW2NlaWxvbWV0ZXJdIFtjaW5kZXJd?= =?utf-8?b?IFtnbGFuY2VdIFtoZWF0XSBbaG9yaXpvbl0gW2tleXN0b25lXSBbbmV1dHJv?= =?utf-8?b?bl0gW25vdmFdIFtzd2lmdF0gW3Ryb3ZlXSBBdGxhbnRhIFN1bW1pdCDigJMg?= =?utf-8?q?Discuss_docs_process_and_tool_improvements?= In-Reply-To: <20140507204338.GA22118@hellgate.ch> References: <CAD0KtVGzg367fV8QjvBUA5GXjaa4vcri2B0TB00AhiyaUmGdaA@mail.gmail.com> <20140507204338.GA22118@hellgate.ch> Message-ID: <536BAB8A.4020900@b1-systems.de> On 05/07/2014 10:43 PM, Roger Luethi wrote: > The people who are qualified to contribute to the docs are usually not > non-technical people, but they can't spend hours setting up an environment > just to work on docs. IMHO good documentation (or scripts, or VM downloads) > that make it easy to create a complete, working environment for testing and > building documentation would go a long way towards making contributions > easier. NOTE: The box will soon be available. I think it's a good idea to have an isolated virtual environment for testing and building the documentation. Just created an initial Vagrant box that can be used for testing and building the documentation inside a virtual system. It includes Maven and tox. All documentation repositories (+ openstack-doc-tools) are already pulled (located in /opt/working) and all Maven dependencies are downloaded. There are three scripts available (located in /usr/local/bin) to simplify some doings: * pull.sh: runs git pull in every repository * fetch.sh: runs mvn dependency:copy-dependencies in every directory including a pom.xml * build.sh: builds a specified document in a specified repository For example to build the document admin-guide-cloud in the repository openstack-manuals run build.sh openstack-manuals admin-guide-cloud. The box has a directory "/opt/working" that's synced to the local directory working on the workstation. This way it's possible to edit and commit the files using the already available toolchain on the workstation and to test and build the documents inside the virtual system. As a nit port 8080 on the workstation is forwarded to port 80 on the virtual system. Port 80 simply serves the files located in /opt/working using Nginx. To view the local-files.html simply go to http://localhost:8080/openstack-manuals/doc/. Christian. -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 From berendt at b1-systems.de Thu May 8 16:08:42 2014 From: berendt at b1-systems.de (Christian Berendt) Date: Thu, 08 May 2014 18:08:42 +0200 Subject: [Openstack-docs] =?utf-8?b?W0RvY10gW2NlaWxvbWV0ZXJdIFtjaW5kZXJd?= =?utf-8?b?IFtnbGFuY2VdIFtoZWF0XSBbaG9yaXpvbl0gW2tleXN0b25lXSBbbmV1dHJv?= =?utf-8?b?bl0gW25vdmFdIFtzd2lmdF0gW3Ryb3ZlXSBBdGxhbnRhIFN1bW1pdCDigJMg?= =?utf-8?q?Discuss_docs_process_and_tool_improvements?= In-Reply-To: <536BAB8A.4020900@b1-systems.de> References: <CAD0KtVGzg367fV8QjvBUA5GXjaa4vcri2B0TB00AhiyaUmGdaA@mail.gmail.com> <20140507204338.GA22118@hellgate.ch> <536BAB8A.4020900@b1-systems.de> Message-ID: <536BAC0A.3030903@b1-systems.de> On 05/08/2014 06:06 PM, Christian Berendt wrote: > NOTE: The box will soon be available. Opened a review request for openstack-doc-tools: https://review.openstack.org/#/c/92867/ -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 From anne at openstack.org Thu May 8 16:42:02 2014 From: anne at openstack.org (Anne Gentle) Date: Thu, 8 May 2014 09:42:02 -0700 Subject: [Openstack-docs] =?utf-8?b?W0RvY10gW2NlaWxvbWV0ZXJdIFtjaW5kZXJd?= =?utf-8?b?IFtnbGFuY2VdIFtoZWF0XSBbaG9yaXpvbl0gW2tleXN0b25lXSBbbmV1?= =?utf-8?q?tron=5D_=5Bnova=5D_=5Bswift=5D_=5Btrove=5D_Atlanta_Summi?= =?utf-8?q?t_=E2=80=93_Discuss_docs_process_and_tool_improvements?= In-Reply-To: <20140507204338.GA22118@hellgate.ch> References: <CAD0KtVGzg367fV8QjvBUA5GXjaa4vcri2B0TB00AhiyaUmGdaA@mail.gmail.com> <20140507204338.GA22118@hellgate.ch> Message-ID: <CAD0KtVHkSuHxj6C2asf7e-gbaKvcygGFEnEtVDnai_5pqhdSCA@mail.gmail.com> On Wed, May 7, 2014 at 1:43 PM, Roger Luethi <rl at patchworkscience.org>wrote: > On Wed, 07 May 2014 09:16:48 -0700, Anne Gentle wrote: > > Why not? The responses to my recent survey about doc contributions > indicate > > that the top barriers to docs? contributions are: > > > > - Tools: DocBook and WADL are difficult > > DocBook may be a pain to set up, but editing DocBook documents is hardly > more difficult than Markdown, RST or any other solution will be by the time > you have added all the features you want to have. > Yep, I realize DocBook fulfills many if not all of the requirements, plus it's what's used within much of RedHat and we have a translation toolchain built for it. These are compelling except for the survey results indicating it's a barrier. I'd like to stick to discussion of the requirements. I just named two possible requirements, should those be included as well? Thanks for the input Roger, you're exactly who we're trying to reach out to for docs, and your input is super valuable. Anne > > Formatting docs is hard because the style guides demand that numerous > rules be considered. Ditching DocBook won't change that. > > > - Subject-matter expertise: People do not have test environments and they > > feel that they don't know enough to contribute. Also, 70% of the > > respondents to the survey work on or consume OpenStack fewer than 10 > hours > > a week. > > The people who are qualified to contribute to the docs are usually not > non-technical people, but they can't spend hours setting up an environment > just to work on docs. IMHO good documentation (or scripts, or VM downloads) > that make it easy to create a complete, working environment for testing and > building documentation would go a long way towards making contributions > easier. > > Roger > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140508/b4237916/attachment.html> From anne at openstack.org Thu May 8 17:05:44 2014 From: anne at openstack.org (Anne Gentle) Date: Thu, 8 May 2014 10:05:44 -0700 Subject: [Openstack-docs] =?utf-8?b?W0RvY10gW2NlaWxvbWV0ZXJdIFtjaW5kZXJd?= =?utf-8?b?IFtnbGFuY2VdIFtoZWF0XSBbaG9yaXpvbl0gW2tleXN0b25lXSBbbmV1?= =?utf-8?q?tron=5D_=5Bnova=5D_=5Bswift=5D_=5Btrove=5D_Atlanta_Summi?= =?utf-8?q?t_=E2=80=93_Discuss_docs_process_and_tool_improvements?= In-Reply-To: <536BAB8A.4020900@b1-systems.de> References: <CAD0KtVGzg367fV8QjvBUA5GXjaa4vcri2B0TB00AhiyaUmGdaA@mail.gmail.com> <20140507204338.GA22118@hellgate.ch> <536BAB8A.4020900@b1-systems.de> Message-ID: <CAD0KtVEO8zsv9b2-97a8pFbvS35qamoNa3YrNof+DhF8k_tJbQ@mail.gmail.com> On Thu, May 8, 2014 at 9:06 AM, Christian Berendt <berendt at b1-systems.de>wrote: > On 05/07/2014 10:43 PM, Roger Luethi wrote: > >> The people who are qualified to contribute to the docs are usually not >> non-technical people, but they can't spend hours setting up an environment >> just to work on docs. IMHO good documentation (or scripts, or VM >> downloads) >> that make it easy to create a complete, working environment for testing >> and >> building documentation would go a long way towards making contributions >> easier. >> > > NOTE: The box will soon be available. > > I think it's a good idea to have an isolated virtual environment for > testing and building the documentation. > I think this is cool, but to give an idea of some of the comments, I think people are having trouble testing OpenStack itself to make sure the docs are accurate. Examples: "Not sure I have the appropriate expertise." "...while I know how a system should be *configured*, I know little about the *install* process." "...it's often so much work to get a proper patch in because there are often so many calls that need to be made just to get to the point of where you want to make the fix. e.g. To create a Neutron port you first need to create a Net and then a Subnet and there are ton of little bits of info necessary for those calls. It becomes a non-starter, when you're strapped for time. The problem is intrinsic to deep APIs so I've got no idea what could help here." Also, to clarify, I believe there's more hesitation and doubt around WADL than DocBook echoed in the survey. I love this idea of a vagrant box for building docs though, will review! Thanks, Anne > > Just created an initial Vagrant box that can be used for testing and > building the documentation inside a virtual system. > > It includes Maven and tox. All documentation repositories (+ > openstack-doc-tools) are already pulled (located in /opt/working) and all > Maven dependencies are downloaded. > > There are three scripts available (located in /usr/local/bin) to simplify > some doings: > > * pull.sh: runs git pull in every repository > * fetch.sh: runs mvn dependency:copy-dependencies in every directory > including a pom.xml > * build.sh: builds a specified document in a specified repository > > For example to build the document admin-guide-cloud in the repository > openstack-manuals run build.sh openstack-manuals admin-guide-cloud. > > The box has a directory "/opt/working" that's synced to the local > directory working on the workstation. This way it's possible to edit and > commit the files using the already available toolchain on the workstation > and to test and build the documents inside the virtual system. > > As a nit port 8080 on the workstation is forwarded to port 80 on the > virtual system. Port 80 simply serves the files located in /opt/working > using Nginx. To view the local-files.html simply go to > http://localhost:8080/openstack-manuals/doc/. > > Christian. > > -- > Christian Berendt > Cloud Computing Solution Architect > Mail: berendt at b1-systems.de > > B1 Systems GmbH > Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de > GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140508/51b20b14/attachment.html> From shaunm at gnome.org Fri May 9 15:47:33 2014 From: shaunm at gnome.org (Shaun McCance) Date: Fri, 09 May 2014 11:47:33 -0400 Subject: [Openstack-docs] [Openstack-i18n] Switch to itstool for docs translation? In-Reply-To: <53662589.2090504@suse.com> References: <1399121582.24585.10.camel@verso> <53662589.2090504@suse.com> Message-ID: <1399650453.2275.131.camel@recto> On Sun, 2014-05-04 at 13:33 +0200, Andreas Jaeger wrote: > On 05/03/2014 02:53 PM, Shaun McCance wrote: > > Hi all, > > > > I've been working on switching the docs translation infrastructure over > > to itstool. This affects openstack-manuals, operations-guide, and > > api-site. The current tools are based on xml2po, but they don't call > > xml2po directly. Instead, they import xml2po and mess around with its > > internals to get some custom behavior. > > > > itstool is designed to handle custom behavior with rules from the W3C > > Internationalization Tag Set (ITS). You can see the ITS I put together > > so far here: > > > > https://review.openstack.org/#/c/91869/3/os_doc_tools/resources/openstack.its,unified > > > > Using ITS also allows us to do local ITS attributes to override the > > behavior for specific elements. See a simple example here: > > > > https://review.openstack.org/#/c/91872/1/api-quick-start/src/docbkx/api-quick-start-intro.xml,unified > > > > Most messages in the PO files will be the same. The one big difference > > will be in how placeholders are done when there's a block-level element > > inside a block-level element (a practice I discourage anyway). > > Could you give an example, please? In the user-guide, in section_dashboard_manage_images.xml, there's an itemizedlist inside a para. An itemizedlist is a block-level element, so it starts one or more new PO messages. The message for the para gets a placeholder element so translators know it's there, and can move it around if necessary. With xml2po, it looks like this: #: doc/user-guide/section_dashboard_manage_images.xml:179(para) msgid "" "In the Update Image dialog box, you can perform the following " "actions: <placeholder-1/>" msgstr "" With itstool, it looks like this: #. (itstool) path: step/para #: doc/user-guide/section_dashboard_manage_images.xml:179 msgid "" "In the Update Image dialog box, you can perform the following " "actions: <_:itemizedlist-1/>" msgstr "" itstool puts all its special elements in a namespace using the _ prefix. (It gets mapped to an internal namespace URI during processing.) This helps prevent conflicts, and it allows the local name of the placeholder element to reflect what kind of thing gets put there, which is helpful. > > I'd like to get input from translators, as well as any other docs folks > > who've worked on this. Most of the document translations are incomplete > > anyway, but it would nevertheless be best to do this at the beginning of > > a release cycle. > > I assume that we can convert the existing translated files in such a way > that we do not loose translations? How to do this properly? Download > current files from transifex, convert into new format, upload converted > files - and then continue translating? Or will it be enough to upload > the pot file and let transfix do the translation? Any translations where the source string is the same will just continue to work. That's the way PO works. I looked into migrating obvious things like the placeholder difference. There are very few translations though. I could maybe fix up 20-30 across all translations of all books. There isn't anything else to migrate. > Did you test a conversation of locale files and reconstructed translated > manuals? Is this just working with the updated tools or are additional > steps needed? Yes. My patch includes also using itstool for generating the DocBook from the PO files. I tested it. It works. > I think we need to ensure with the infra team that itstools are > installed on our machines. That's the big question I haven't been able to answer yet. Preferably at least version 2.0.1. > I see that some patches are dependent on each other and we need to do > certain steps in a specific order. Is this something you can write down > as plan, please? I did write this: https://wiki.openstack.org/wiki/Documentation/Translation#ItsTool_Conversion It has steps that need to be done (roughly) in order. -- Shaun From aj at suse.com Fri May 9 15:57:40 2014 From: aj at suse.com (Andreas Jaeger) Date: Fri, 09 May 2014 17:57:40 +0200 Subject: [Openstack-docs] [Openstack-i18n] Switch to itstool for docs translation? In-Reply-To: <1399650453.2275.131.camel@recto> References: <1399121582.24585.10.camel@verso> <53662589.2090504@suse.com> <1399650453.2275.131.camel@recto> Message-ID: <536CFAF4.2010006@suse.com> On 05/09/2014 05:47 PM, Shaun McCance wrote: > [...] >> I think we need to ensure with the infra team that itstools are >> installed on our machines. > > That's the big question I haven't been able to answer yet. Preferably at > least version 2.0.1. Just talked briefly with the infra team and checked our setup: What is in Ubuntu Precise? I assume the package is not installed but if it's available, we can add rules to the gate machines to have it installed... Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Fri May 9 16:04:41 2014 From: aj at suse.com (Andreas Jaeger) Date: Fri, 09 May 2014 18:04:41 +0200 Subject: [Openstack-docs] [Openstack-i18n] Switch to itstool for docs translation? In-Reply-To: <536CFAF4.2010006@suse.com> References: <1399121582.24585.10.camel@verso> <53662589.2090504@suse.com> <1399650453.2275.131.camel@recto> <536CFAF4.2010006@suse.com> Message-ID: <536CFC99.2040205@suse.com> On 05/09/2014 05:57 PM, Andreas Jaeger wrote: > On 05/09/2014 05:47 PM, Shaun McCance wrote: >> [...] > >>> I think we need to ensure with the infra team that itstools are >>> installed on our machines. >> >> That's the big question I haven't been able to answer yet. Preferably at >> least version 2.0.1. > > Just talked briefly with the infra team and checked our setup: > > What is in Ubuntu Precise? I assume the package is not installed but if > it's available, we can add rules to the gate machines to have it > installed... Shaun, this is in precise: http://packages.ubuntu.com/precise/itstool This is a python package, isn't it? Get 2.0.1 on pypi.python.org and we can install it from there... Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Fri May 9 20:30:13 2014 From: anne at openstack.org (Anne Gentle) Date: Fri, 9 May 2014 15:30:13 -0500 Subject: [Openstack-docs] stable/icehouse branch for openstack-manuals Message-ID: <CAD0KtVH=_m1KwPLhzFvnZS=Wq=YuViNAC8QOMO-r3Yo0dnpAnQ@mail.gmail.com> Hi all, Congrats on the docs release for the Install Guides and Configuration Reference! Huge appreciation vibes to everyone who made the Icehouse release a success for docs. I'm continually grateful for the great group we have working on docs and doc tools. What this means is: - If you have a patch to the install-guide or config-ref files and it affects Icehouse also, in the commit message put "backport: stable/icehouse" so that reviewers know what needs to go to the stable/icehouse branch. - We can now begin documenting Juno changes in those documents. As noted previously, every other document is continuously published, meaning, if a patch is approved, it will be published live. Thanks again, and I hope to see you all in Atlanta. Anne -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140509/b48a81d8/attachment.html> From aj at suse.com Fri May 9 21:08:47 2014 From: aj at suse.com (Andreas Jaeger) Date: Fri, 09 May 2014 23:08:47 +0200 Subject: [Openstack-docs] stable/icehouse branch for openstack-manuals In-Reply-To: <CAD0KtVH=_m1KwPLhzFvnZS=Wq=YuViNAC8QOMO-r3Yo0dnpAnQ@mail.gmail.com> References: <CAD0KtVH=_m1KwPLhzFvnZS=Wq=YuViNAC8QOMO-r3Yo0dnpAnQ@mail.gmail.com> Message-ID: <536D43DF.6070507@suse.com> On 05/09/2014 10:30 PM, Anne Gentle wrote: > Hi all, > > Congrats on the docs release for the Install Guides and Configuration > Reference! Huge appreciation vibes to everyone who made the Icehouse > release a success for docs. I'm continually grateful for the great group > we have working on docs and doc tools. > > What this means is: > - If you have a patch to the install-guide or config-ref files and it > affects Icehouse also, in the commit message put "backport: > stable/icehouse" so that reviewers know what needs to go to the > stable/icehouse branch. > - We can now begin documenting Juno changes in those documents. > > As noted previously, every other document is continuously published, > meaning, if a patch is approved, it will be published live. > > Thanks again, and I hope to see you all in Atlanta. Just noticed that our jobs do not handle icehouse properly - I hope this fixed it: https://review.openstack.org/93129 And we need this patch in our branch for building: https://review.openstack.org/#/c/93124/ I'll push these forward myself and suggest that for now no patches for stable/icehouse get approved until we've verified that everything works. If you look at 93124, you see that the Install Guide and Config Reference have file names with trunk in it - they should have stable/icehouse. Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Sat May 10 06:58:57 2014 From: aj at suse.com (Andreas Jaeger) Date: Sat, 10 May 2014 08:58:57 +0200 Subject: [Openstack-docs] stable/icehouse branch for openstack-manuals In-Reply-To: <536D43DF.6070507@suse.com> References: <CAD0KtVH=_m1KwPLhzFvnZS=Wq=YuViNAC8QOMO-r3Yo0dnpAnQ@mail.gmail.com> <536D43DF.6070507@suse.com> Message-ID: <536DCE31.10701@suse.com> On 05/09/2014 11:08 PM, Andreas Jaeger wrote: > On 05/09/2014 10:30 PM, Anne Gentle wrote: >> Hi all, >> >> Congrats on the docs release for the Install Guides and Configuration >> Reference! Huge appreciation vibes to everyone who made the Icehouse >> release a success for docs. I'm continually grateful for the great group >> we have working on docs and doc tools. >> >> What this means is: >> - If you have a patch to the install-guide or config-ref files and it >> affects Icehouse also, in the commit message put "backport: >> stable/icehouse" so that reviewers know what needs to go to the >> stable/icehouse branch. >> - We can now begin documenting Juno changes in those documents. >> >> As noted previously, every other document is continuously published, >> meaning, if a patch is approved, it will be published live. >> >> Thanks again, and I hope to see you all in Atlanta. > > Just noticed that our jobs do not handle icehouse properly - I hope this > fixed it: > https://review.openstack.org/93129 This breaks all gate jobs now ;( I'm sorry, Andreas > And we need this patch in our branch for building: > https://review.openstack.org/#/c/93124/ > > I'll push these forward myself and suggest that for now no patches for > stable/icehouse get approved until we've verified that everything works. > > If you look at 93124, you see that the Install Guide and Config > Reference have file names with trunk in it - they should have > stable/icehouse. > > Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Sat May 10 11:27:41 2014 From: aj at suse.com (Andreas Jaeger) Date: Sat, 10 May 2014 13:27:41 +0200 Subject: [Openstack-docs] stable/icehouse branch for openstack-manuals In-Reply-To: <536DCE31.10701@suse.com> References: <CAD0KtVH=_m1KwPLhzFvnZS=Wq=YuViNAC8QOMO-r3Yo0dnpAnQ@mail.gmail.com> <536D43DF.6070507@suse.com> <536DCE31.10701@suse.com> Message-ID: <536E0D2D.5020706@suse.com> On 05/10/2014 08:58 AM, Andreas Jaeger wrote: > On 05/09/2014 11:08 PM, Andreas Jaeger wrote: >> On 05/09/2014 10:30 PM, Anne Gentle wrote: >>> Hi all, >>> >>> Congrats on the docs release for the Install Guides and Configuration >>> Reference! Huge appreciation vibes to everyone who made the Icehouse >>> release a success for docs. I'm continually grateful for the great group >>> we have working on docs and doc tools. >>> >>> What this means is: >>> - If you have a patch to the install-guide or config-ref files and it >>> affects Icehouse also, in the commit message put "backport: >>> stable/icehouse" so that reviewers know what needs to go to the >>> stable/icehouse branch. >>> - We can now begin documenting Juno changes in those documents. >>> >>> As noted previously, every other document is continuously published, >>> meaning, if a patch is approved, it will be published live. >>> >>> Thanks again, and I hope to see you all in Atlanta. >> >> Just noticed that our jobs do not handle icehouse properly - I hope this >> fixed it: >> https://review.openstack.org/93129 > > This breaks all gate jobs now ;( I'm sorry, The infra job was reverted (Clark was sleep walking ; - thanks!). The setup was broken on the havana branch as well. Fortunately, openstack-doc-test has an option to set the values manually that are read from the properties file and I've set these values now. I'm double checking these patches now and if they pass, will self-approve to unbreak the tree: https://review.openstack.org/93183 https://review.openstack.org/93182 Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Sat May 10 12:57:20 2014 From: aj at suse.com (Andreas Jaeger) Date: Sat, 10 May 2014 14:57:20 +0200 Subject: [Openstack-docs] stable/icehouse branch for openstack-manuals In-Reply-To: <536E0D2D.5020706@suse.com> References: <CAD0KtVH=_m1KwPLhzFvnZS=Wq=YuViNAC8QOMO-r3Yo0dnpAnQ@mail.gmail.com> <536D43DF.6070507@suse.com> <536DCE31.10701@suse.com> <536E0D2D.5020706@suse.com> Message-ID: <536E2230.1050204@suse.com> On 05/10/2014 01:27 PM, Andreas Jaeger wrote: > [...] > The infra job was reverted (Clark was sleep walking ; - thanks!). > > The setup was broken on the havana branch as well. Fortunately, > openstack-doc-test has an option to set the values manually that are > read from the properties file and I've set these values now. > > I'm double checking these patches now and if they pass, will > self-approve to unbreak the tree: > https://review.openstack.org/93183 > https://review.openstack.org/93182 > > Andreas Everything looks fine to me now - feel free to use the Icehouse branch ;) Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Sun May 11 19:16:08 2014 From: aj at suse.com (Andreas Jaeger) Date: Sun, 11 May 2014 21:16:08 +0200 Subject: [Openstack-docs] Unused files in openstack-manuals - please check them In-Reply-To: <53458FCC.9080200@suse.com> References: <53458FCC.9080200@suse.com> Message-ID: <536FCC78.5010400@suse.com> On 04/09/2014 08:22 PM, Andreas Jaeger wrote: > I've just send a couple of patches to remove or include currently unused > files. With the patches I'm going to submit, once I have network again, these files remain as orphaned files (besides the training guide): common/section_cli_keystone_apiv3.xml common/section_cli_keystone_credentials.xml common/section_cli_nova_fileinjection.xml common/section_cli_nova_metadata.xml common/section_cli_nova_secgroups.xml common/section_cli_nova_sshkeys.xml common/section_dashboard_launch_instances_from_image.xml common/section_keystone_db_sync.xml common/section_user-data.xml common/section_using-vnc-console.xml Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Mon May 12 18:22:06 2014 From: anne at openstack.org (Anne Gentle) Date: Mon, 12 May 2014 13:22:06 -0500 Subject: [Openstack-docs] Input at the Summit on Disqus comments Message-ID: <CAD0KtVHbysXnMA3FNGZDP2hmz-jTJE=z7cmOieqp0QGKU6GrsA@mail.gmail.com> Hi all, Today after one of the Ops discussions I had a conversation with a sysadmin who really misses the Disqus comments, and doesn't think the link to ask.openstack.org offers enough context that a doc page offers. I told him we really wanted the widget from ask that we could embed like Disqus comments, he said that would be better. Just wanting to let us all know one bit of input on turning off comments. I'm not wanting to reverse the decision, just letting us know that we have some input that there's a sense of loss of context. For Icehouse, only the install guide has comments turned on, and I had logged a bug last week asking for those to be turned off. Andreas has a patch ready at https://review.openstack.org/#/c/93280 and I just wanted to make sure we are in tune once this change happens so that we can offer lots of doc links and context on ask.openstack.org. Also, if anyone is interested in coding the widget for ask.openstack.orgthat could be embedded, please let me connect you! It seems like it would be a real win. Thanks, Anne -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140512/33581f21/attachment.html> From gauvain.pocentek at objectif-libre.com Tue May 13 19:28:40 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Tue, 13 May 2014 21:28:40 +0200 Subject: [Openstack-docs] config-ref blueprints Message-ID: <aa24a26606361e5b56dff02f12092112@objectif-libre.com> Hello guys, I've drafted a couple blueprints for the config ref, I'd like to hear some feedback. A live discussion at the summit would be nice but I wanted to include everyone in the loop. [1] deals with the fact that we don't have a single page listing all available options for each OS project (AFAIK). For [2] the idea is to improve the documentation about options common to all the projects, but also avoid duplication. Thanks, Gauvain [1]: https://blueprints.launchpad.net/openstack-manuals/+spec/config-ref-all-options-table [2]: https://blueprints.launchpad.net/openstack-manuals/+spec/config-ref-common-sections From anne at openstack.org Tue May 13 21:41:35 2014 From: anne at openstack.org (Anne Gentle) Date: Tue, 13 May 2014 16:41:35 -0500 Subject: [Openstack-docs] config-ref blueprints In-Reply-To: <aa24a26606361e5b56dff02f12092112@objectif-libre.com> References: <aa24a26606361e5b56dff02f12092112@objectif-libre.com> Message-ID: <CAD0KtVHp+270xOEo=MkvaF6KjVZZeRFA4wntn3GAK=f+NKgBsQ@mail.gmail.com> On Tue, May 13, 2014 at 2:28 PM, Gauvain Pocentek < gauvain.pocentek at objectif-libre.com> wrote: > Hello guys, > > I've drafted a couple blueprints for the config ref, I'd like to hear some > feedback. A live discussion at the summit would be nice but I wanted to > include everyone in the loop. > > [1] deals with the fact that we don't have a single page listing all > available options for each OS project (AFAIK). > Do you have a request from the community for this single page listing? I am not getting this type of input informally so I am not sure where this request comes from. > > For [2] the idea is to improve the documentation about options common to > all the projects, but also avoid duplication. > I think avoiding duplication is a good goal here. A higher priority request to me, that I've gotten from various conversations, is that the reference listing is great, but the more requested next document is for combinations of configurations for a particular goal in mind. I think some of this type of documentation may come out of the design guide book sprint, but I'd also like us to think about how we might write this type of documentation. Thanks Gauvain for brining this to the list! Anne > > Thanks, > Gauvain > > [1]: https://blueprints.launchpad.net/openstack-manuals/+spec/ > config-ref-all-options-table > [2]: https://blueprints.launchpad.net/openstack-manuals/+spec/ > config-ref-common-sections > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140513/eb8a2a7d/attachment.html> From gauvain.pocentek at objectif-libre.com Tue May 13 22:08:26 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Wed, 14 May 2014 00:08:26 +0200 Subject: [Openstack-docs] config-ref blueprints In-Reply-To: <CAD0KtVHp+270xOEo=MkvaF6KjVZZeRFA4wntn3GAK=f+NKgBsQ@mail.gmail.com> References: <aa24a26606361e5b56dff02f12092112@objectif-libre.com> <CAD0KtVHp+270xOEo=MkvaF6KjVZZeRFA4wntn3GAK=f+NKgBsQ@mail.gmail.com> Message-ID: <7f49b7c31f1312b15d03501c7ba63eea@objectif-libre.com> Le 2014-05-13 23:41, Anne Gentle a ?crit?: > On Tue, May 13, 2014 at 2:28 PM, Gauvain Pocentek > <gauvain.pocentek at objectif-libre.com> wrote: > >> Hello guys, >> >> I've drafted a couple blueprints for the config ref, I'd like to hear >> some feedback. A live discussion at the summit would be nice but I >> wanted to include everyone in the loop. >> >> [1] deals with the fact that we don't have a single page listing all >> available options for each OS project (AFAIK). > > Do you have a request from the community for this single page > listing? I am not getting this type of input informally so I am not > sure where this request comes from. I don't think we've had a request from the community. But we discussed this kind of changes a while ago (http://lists.openstack.org/pipermail/openstack-docs/2014-March/004036.html). >> For [2] the idea is to improve the documentation about options common >> to all the projects, but also avoid duplication. > > I think avoiding duplication is a good goal here.? > > A higher priority request to me, that I've gotten from various > conversations, is that the reference listing is great, but the more > requested next document is for combinations of configurations for a > particular goal in mind. I think some of this type of documentation > may come out of the design guide book sprint, but I'd also like us to > think about how we might write this type of documentation. Some kind of configuration cookbook? I like the idea :) Isn't that something that would better be sitting in the Cloud Admin Guide rather than the config-ref? Either way it's something that would probably be very useful to users, and that would match the idea behind the spec (how do I use Qpid/Rabbit? How do I use keystone token authentication?). > > Thanks Gauvain for brining this to the list! Thanks for your answer :) Gauvain From anne at openstack.org Wed May 14 18:24:46 2014 From: anne at openstack.org (Anne Gentle) Date: Wed, 14 May 2014 13:24:46 -0500 Subject: [Openstack-docs] Documentation Pod at the Summit Message-ID: <CAD0KtVFRaHrf2G8eLTTvc_+HEvH-kixS4fh6degJQPtuMpUHcg@mail.gmail.com> Hi all, If you're in Atlanta for the Design Summit, I wanted to be sure you know about the Documentation Pod downstairs from the developer's lounge. It's pod 12 in room 204. Thanks, Anne -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140514/c45c9b41/attachment.html> From aj at suse.com Thu May 15 11:02:57 2014 From: aj at suse.com (Andreas Jaeger) Date: Thu, 15 May 2014 07:02:57 -0400 Subject: [Openstack-docs] [Openstack-i18n] Switch to itstool for docs translation? In-Reply-To: <1399121582.24585.10.camel@verso> References: <1399121582.24585.10.camel@verso> Message-ID: <53749EE1.105@suse.com> I discussed this a bit with Daisy and Akihiro at the summit and both need some more investigation on this. Let me re-share some pointers for all here. I suggest that some of you translators have a look at patch 90766 and this thread and figure out whether there are any problems. This move to itstools is a move to newer and maintained tools that will simplify our live on the tools side. It only affects docs translation - the manuals - and not the core projects. So, this is related to all the resources you find on transifex under openstack-manuals. I'd like to see this happen because of the improvements it brings, so please evaluate it and speak up if you see problems - a "go ahead" would be also appreciated. Note that Daisy needs to approve the blue print before this will go in. Patch set 1 of patch https://review.openstack.org/#/c/90766/ shows the changes to the locale files, for example: https://review.openstack.org/#/c/90766/1/doc/user-guide-admin/locale/en_AU.po These patches show what can be done with the tools - marking some sections as non-translatable (and thus not show up in transifex) sounds like a great idea to me: https://review.openstack.org/#/c/91873/ https://review.openstack.org/#/c/91872/ The conversation of the code is shown here: https://review.openstack.org/#/c/91869/ Especially this patch is interesting, it shows how easy it is to filter out what gets translated and what not: https://review.openstack.org/#/c/91869/3/os_doc_tools/resources/openstack.its https://blueprints.launchpad.net/openstack-manuals/+spec/itstool-for-docs Full specification: https://wiki.openstack.org/wiki/Documentation/Translation#ItsTool_Conversion Shaun, for using itstool on the infra machines, we really need to have it on pypi. Can you make this happen, please? Also, please add to the commit message of each of your patches: blueprint itstool-for-docs Thanks, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Thu May 15 12:41:51 2014 From: anne at openstack.org (Anne Gentle) Date: Thu, 15 May 2014 07:41:51 -0500 Subject: [Openstack-docs] What's Up Doc - Atlanta Summit edition Message-ID: <CAD0KtVGj5q-sKXn5xELFwOxLDFZ7nR0HpD4bu0vR8biv7XX55Q@mail.gmail.com> Hi all from Atlanta where we have over 4,000 gathered to collaborate in person! I'm enjoying the week immensely. My favorite so far has to be the Women of OpenStack gathering last night. We are onto something cool in this community. Tuesday we had two sessions about cross-project documentation and though Nick was worried there would be overlap, we got great input from each quite different from the other. My takeaway is that the developers are very happy to hand doc tasks over to "real" writers but that they can help us with the specs, with excellent commit messages, and we want to follow the specs lead by making an excellent template for commit messages and continue to spread the word about DocImpact. [1] For the cross-project session about requirements for our tooling, one takeaway is that we won't fix what isn't broken. [2] Also, even if for some books we discontinue the use of DocBook, places like RedHat will still figure out how to use the upstream documentation and continue to improve it. I really want to emphasize a shift to end-user docs this release. We created developer.openstack.org this past release, and I want to see how we can build out more end-user content for application developers. I've been in many of the CLI and SDK tracks and thinking hard about how to make the best deliverables we can. Please offer input if you're interested! I'm also going to write a roadmap for each document -- and though yesterday I said I'd put those on the wiki, I think I'll put a roadmap file in with each document. Then anyone who wants to figure out where the book stands and what they might do to work on it that's high priority, they can. The Install Guide session went well yesterday and one decision we came to after much discussion was to standardize on manual updates of the config files rather than hiding them behind openstack-config commands. Matt has a great summary in the Etherpad for the session on the tasks for the next release. [3] I've also been talking to Ironic team about how to document their installation process and while in the session on Install we did not have anyone who wanted bare metal in that guide, it may make sense to put a chapter about why you would use a project like Ironic for installation in the Cloud Admin Guide. I'd love input on where that fits in our current documentation set. I also have to share a great comment from the User Survey [4] that Tim Bell is especially delighted with because he knows how disappointed people were in the docs 18 months ago, even 12 months ago. "Over the last 6 months I think the documentation has improved significantly. I have seen others recently hold up OpenStack docs as a model to strive for." We are making a difference across the world and our hard work is paying off. Thanks to all of you who are a part of this effort -- nearly 200 of us this last six months. I can't express enough how grateful I am to have such dedication shine through in OpenStack docs. Today we have "Patching the documentation process" at 9:50. Tomorrow we'll talk about Continuous publishing and automation at 9:00, and discuss how to Beef up User and Ops Guides for integrated projects at 11:40. Lots more work to do, let's tackle this! Anne 1. https://etherpad.openstack.org/p/easier_documentation_for_developers 2. https://etherpad.openstack.org/p/summit-session-cross-project-docs 3. https://etherpad.openstack.org/p/installation-guide-audit 4. http://www.slideshare.net/ryan-lane/openstack-atlanta-user-survey slide 24 -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140515/f8cc874b/attachment.html> From gauvain.pocentek at objectif-libre.com Thu May 15 15:34:04 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Thu, 15 May 2014 17:34:04 +0200 Subject: [Openstack-docs] [Heat][Documentation] Heat template documentation Message-ID: <90d4482bcd0b7a52c7262631ffd3baef@objectif-libre.com> Hello, This mail probably mainly concerns the doc team, but I guess that the heat team wants to know what's going on. We've shortly discussed the state of heat documentation with Anne Gentle and Andreas Jaeger yesterday, and I'd like to share what we think would be nice to do. Currently we only have a small section in the user guide that describes how to start a stack, but nothing documenting how to write templates. The heat developer doc provides a good reference, but I think it's not easy to use to get started. So the idea is to add an "OpenStack Orchestration" chapter in the user guide that would document how to use a cloud with heat, and how to write templates. I've drafted a spec to keep track of this at [0]. Let me know if this sounds OK to you all. Gauvain Pocentek Objectif Libre - Infrastructure et Formations Linux http://www.objectif-libre.com [0]: https://blueprints.launchpad.net/openstack-manuals/+spec/heat-templates From gauvain.pocentek at objectif-libre.com Thu May 15 15:40:40 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Thu, 15 May 2014 17:40:40 +0200 Subject: [Openstack-docs] Policy for approving backports Message-ID: <e8ae767f5c80279bb44a1507828e3116@objectif-libre.com> Hello, I guess I should have asked this during this morning's doc session at the summit, but I hadn't had real coffee yet (only decaf!). How do we handle backports reviews? Is one +2 enough (that's what Andreas used to do during the post havana backport storm)? Is self approval a valid option? I'd like to hear what you guys think. Thanks, Gauvain Pocentek Objectif Libre - Infrastructure et Formations Linux http://www.objectif-libre.com From tom at openstack.org Thu May 15 15:48:05 2014 From: tom at openstack.org (Tom Fifield) Date: Thu, 15 May 2014 11:48:05 -0400 Subject: [Openstack-docs] Policy for approving backports In-Reply-To: <e8ae767f5c80279bb44a1507828e3116@objectif-libre.com> References: <e8ae767f5c80279bb44a1507828e3116@objectif-libre.com> Message-ID: <5374E1B5.1090004@openstack.org> On 15/05/14 11:40, Gauvain Pocentek wrote: > Hello, > > I guess I should have asked this during this morning's doc session at > the summit, but I hadn't had real coffee yet (only decaf!). > > How do we handle backports reviews? Is one +2 enough (that's what > Andreas used to do during the post havana backport storm)? Is self > approval a valid option? > > I'd like to hear what you guys think. IMO: one sanity-check +2 from someone who is not the submitter From gauvain.pocentek at objectif-libre.com Thu May 15 15:54:27 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Thu, 15 May 2014 17:54:27 +0200 Subject: [Openstack-docs] [Heat][Documentation] Heat template documentation In-Reply-To: <90d4482bcd0b7a52c7262631ffd3baef@objectif-libre.com> References: <90d4482bcd0b7a52c7262631ffd3baef@objectif-libre.com> Message-ID: <aacbfe99975184407bffdd75638e7171@objectif-libre.com> (Resending to add openstack-dev) Gauvain Pocentek Objectif Libre - Infrastructure et Formations Linux http://www.objectif-libre.com Le 2014-05-15 17:34, Gauvain Pocentek a ?crit?: > Hello, > > This mail probably mainly concerns the doc team, but I guess that the > heat team wants to know what's going on. > > We've shortly discussed the state of heat documentation with Anne > Gentle and Andreas Jaeger yesterday, and I'd like to share what we > think would be nice to do. > > Currently we only have a small section in the user guide that > describes how to start a stack, but nothing documenting how to write > templates. The heat developer doc provides a good reference, but I > think it's not easy to use to get started. > > So the idea is to add an "OpenStack Orchestration" chapter in the > user guide that would document how to use a cloud with heat, and how > to write templates. > > I've drafted a spec to keep track of this at [0]. > > Let me know if this sounds OK to you all. > > Gauvain Pocentek > > Objectif Libre - Infrastructure et Formations Linux > http://www.objectif-libre.com > > [0]: > https://blueprints.launchpad.net/openstack-manuals/+spec/heat-templates > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs From aj at suse.com Thu May 15 16:08:28 2014 From: aj at suse.com (Andreas Jaeger) Date: Thu, 15 May 2014 12:08:28 -0400 Subject: [Openstack-docs] Policy for approving backports In-Reply-To: <5374E1B5.1090004@openstack.org> References: <e8ae767f5c80279bb44a1507828e3116@objectif-libre.com> <5374E1B5.1090004@openstack.org> Message-ID: <5374E67C.40504@suse.com> On 05/15/2014 11:48 AM, Tom Fifield wrote: > On 15/05/14 11:40, Gauvain Pocentek wrote: >> Hello, >> >> I guess I should have asked this during this morning's doc session at >> the summit, but I hadn't had real coffee yet (only decaf!). >> >> How do we handle backports reviews? Is one +2 enough (that's what >> Andreas used to do during the post havana backport storm)? Is self >> approval a valid option? >> >> I'd like to hear what you guys think. > > IMO: one sanity-check +2 from someone who is not the submitter Agreed. Also, backports should not be edited, if there are problems noticed, we should do a patch for master to fix those and backport that one, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Thu May 15 20:49:19 2014 From: aj at suse.com (Andreas Jaeger) Date: Thu, 15 May 2014 16:49:19 -0400 Subject: [Openstack-docs] Translation gate for doc jobs Message-ID: <5375284F.3030208@suse.com> Inspired by some discussions here at the summit, I'd like to setup some translation gate for jobs. Patch https://review.openstack.org/93526 (merged) sets up a test that can be invoked with "tox -e checklang" which builds all "supported" manuals. I propose the following: * Setup checking/gating jobs that runs this test and mark it as non-voting. * Create policy on how to handle failures. Proposed policy: * We only gate on manual/language combinations that are translated sufficiently. Right now that's for openstack-manuals Japanese with the Security Guide, HA Guide and Install Guides only. * If an import from transifex fails, creates a failure, we do not approve the import. * If any other patch fails, the failure might get ignored. * In any case of failure, let's send an email to the openstack-i18n mailing list asking them to investigate and fix. What do you think? Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From tom at openstack.org Fri May 16 12:02:01 2014 From: tom at openstack.org (Tom Fifield) Date: Fri, 16 May 2014 08:02:01 -0400 Subject: [Openstack-docs] Translation gate for doc jobs In-Reply-To: <5375284F.3030208@suse.com> References: <5375284F.3030208@suse.com> Message-ID: <5375FE39.20904@openstack.org> On 15/05/14 16:49, Andreas Jaeger wrote: > Inspired by some discussions here at the summit, I'd like to setup some > translation gate for jobs. > > Patch https://review.openstack.org/93526 (merged) sets up a test that > can be invoked with "tox -e checklang" which builds all "supported" manuals. > > I propose the following: > > * Setup checking/gating jobs that runs this test and mark it as non-voting. > * Create policy on how to handle failures. > > Proposed policy: > * We only gate on manual/language combinations that are translated > sufficiently. Right now that's for openstack-manuals Japanese with the > Security Guide, HA Guide and Install Guides only. > * If an import from transifex fails, creates a failure, we do not > approve the import. > * If any other patch fails, the failure might get ignored. > * In any case of failure, let's send an email to the openstack-i18n > mailing list asking them to investigate and fix. > > What do you think? Good, but I'd prefer the creation of a bug in openstack-i18n on launchpad, instead of a mailing list post. This way people who are interested in fixing such things can get notified by email (through bug tracker subscriptions), and the mailing list is kept clear for people who just want to translate things and participate in the community in other ways :) From gauvain.pocentek at objectif-libre.com Fri May 16 14:05:31 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Fri, 16 May 2014 16:05:31 +0200 Subject: [Openstack-docs] Policy for approving backports In-Reply-To: <5374E67C.40504@suse.com> References: <e8ae767f5c80279bb44a1507828e3116@objectif-libre.com> <5374E1B5.1090004@openstack.org> <5374E67C.40504@suse.com> Message-ID: <fec80c3953ae843bbee513bd22d8a1c8@objectif-libre.com> Le 2014-05-15 18:08, Andreas Jaeger a ?crit?: > On 05/15/2014 11:48 AM, Tom Fifield wrote: >> On 15/05/14 11:40, Gauvain Pocentek wrote: >>> Hello, >>> >>> I guess I should have asked this during this morning's doc session >>> at >>> the summit, but I hadn't had real coffee yet (only decaf!). >>> >>> How do we handle backports reviews? Is one +2 enough (that's what >>> Andreas used to do during the post havana backport storm)? Is self >>> approval a valid option? >>> >>> I'd like to hear what you guys think. >> >> IMO: one sanity-check +2 from someone who is not the submitter > > Agreed. > > Also, backports should not be edited, if there are problems noticed, > we > should do a patch for master to fix those and backport that one, Sounds good to me. Thanks for the feedback! I guess that we could add that info to the upcoming review guide :) Gauvain From gauvain.pocentek at objectif-libre.com Fri May 16 14:23:18 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Fri, 16 May 2014 16:23:18 +0200 Subject: [Openstack-docs] [openstack-dev] [Heat][Documentation] Heat template documentation In-Reply-To: <5374EC0F.7010707@redhat.com> References: <90d4482bcd0b7a52c7262631ffd3baef@objectif-libre.com> <aacbfe99975184407bffdd75638e7171@objectif-libre.com> <5374EC0F.7010707@redhat.com> Message-ID: <508e4c755e0272ea30850b9d333c2d7c@objectif-libre.com> Le 2014-05-15 18:32, Steve Baker a ?crit?: > On 15/05/14 11:54, Gauvain Pocentek wrote: >> (Resending to add openstack-dev) >> >> Gauvain Pocentek >> >> Objectif Libre - Infrastructure et Formations Linux >> http://www.objectif-libre.com >> >> Le 2014-05-15 17:34, Gauvain Pocentek a ?crit : >>> Hello, >>> >>> This mail probably mainly concerns the doc team, but I guess that >>> the >>> heat team wants to know what's going on. >>> >>> We've shortly discussed the state of heat documentation with Anne >>> Gentle and Andreas Jaeger yesterday, and I'd like to share what we >>> think would be nice to do. >>> >>> Currently we only have a small section in the user guide that >>> describes how to start a stack, but nothing documenting how to write >>> templates. The heat developer doc provides a good reference, but I >>> think it's not easy to use to get started. >>> >>> So the idea is to add an "OpenStack Orchestration" chapter in the >>> user guide that would document how to use a cloud with heat, and how >>> to write templates. >>> >>> I've drafted a spec to keep track of this at [0]. >>> >>> Let me know if this sounds OK to you all. >>> >>> Gauvain Pocentek >>> >>> Objectif Libre - Infrastructure et Formations Linux >>> http://www.objectif-libre.com >>> >>> [0]: >>> https://blueprints.launchpad.net/openstack-manuals/+spec/heat-templates >>> > Thanks for raising this, I do hope I can help writing the content. Thanks! > In > addition to this, we will at some point need to port the resource > reference generation to this guide as well. That would be nice. I'm not sure if the user guide is the proper book, but we'll figure out where to put this with the doc team. One thing that would be really useful for users would be to have versioned references. Correct me if I'm wrong, but I think that only the trunk doc is published on the developers doc site. It makes it hard to know which resources are available for a specific version of openstack. Thanks, Gauvain From anne at openstack.org Fri May 16 15:13:48 2014 From: anne at openstack.org (Anne Gentle) Date: Fri, 16 May 2014 10:13:48 -0500 Subject: [Openstack-docs] [Heat][Documentation] Heat template documentation In-Reply-To: <90d4482bcd0b7a52c7262631ffd3baef@objectif-libre.com> References: <90d4482bcd0b7a52c7262631ffd3baef@objectif-libre.com> Message-ID: <CAD0KtVF6qnO4-Kd7ELxJZU53r7jtTSv7mCJG3ZVyJu-C+LxtYA@mail.gmail.com> On Thu, May 15, 2014 at 10:34 AM, Gauvain Pocentek < gauvain.pocentek at objectif-libre.com> wrote: > Hello, > > This mail probably mainly concerns the doc team, but I guess that the heat > team wants to know what's going on. > > We've shortly discussed the state of heat documentation with Anne Gentle > and Andreas Jaeger yesterday, and I'd like to share what we think would be > nice to do. > > Currently we only have a small section in the user guide that describes > how to start a stack, but nothing documenting how to write templates. The > heat developer doc provides a good reference, but I think it's not easy to > use to get started. > > So the idea is to add an "OpenStack Orchestration" chapter in the user > guide that would document how to use a cloud with heat, and how to write > templates. > > I've drafted a spec to keep track of this at [0]. > > I'd like to experiment a bit with converting the End User Guide to an easier markup to enable more contributors to it. Perhaps bringing in Orchestration is a good point to do this, plus it may help address the auto-generation Steve mentions. The loss would be the single sourcing of the End User Guide and Admin User Guide as well as loss of PDF output and loss of translation. If these losses are worthwhile for easier maintenance and to encourage contributions from more cloud consumers, then I'd like to try an experiment with it. The experiment would be to have a new repo set up, openstack/user-guide and use the docs-core team as reviewers on it. Convert the End User Guide from DocBook to RST and build with Sphinx. Use the oslosphinx tempate for output. But what I don't know is if it's possible to build the automated output outside of the openstack/heat repo, does anyone have interest in doing a proof of concept on this? I'd also like input on the loss of features I'm describing above. Is this worth experimenting with? Thanks, Anne > Let me know if this sounds OK to you all. > > Gauvain Pocentek > > Objectif Libre - Infrastructure et Formations Linux > http://www.objectif-libre.com > > [0]: https://blueprints.launchpad.net/openstack-manuals/+spec/ > heat-templates > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140516/db24f774/attachment.html> From anne at openstack.org Fri May 16 15:20:01 2014 From: anne at openstack.org (Anne Gentle) Date: Fri, 16 May 2014 10:20:01 -0500 Subject: [Openstack-docs] Security Guide moving and interested reviewers Message-ID: <CAD0KtVHdUo0DGATzQRqd2gjZPDCtpWBiJQGC+UPTQtB4s6hwvA@mail.gmail.com> Hi all, Bryan Payne and Andreas and I met this week about updates for the Security Guide. We want to move the book into its own repo. [1] The move helps with automatically incorporating the OpenStack Security Notes into an appendix with the Security Guide itself. If you're interested in being a core reviewer on the Security Guide, please let me and Bryan Payne know. Your responsibilities would be to review changes to the Security Guide and OpenStack Security Notes and follow the review guidelines for technical reviews and doc-related reviews. I didn't want to voluntell the entire docs-core team so I'm coming to the list to ask about interest. If there are any ramifications we haven't considered, please let us know! Anne 1. https://review.openstack.org/#/c/93747/ -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140516/70e1c334/attachment.html> From gauvain.pocentek at objectif-libre.com Fri May 16 18:10:35 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Fri, 16 May 2014 20:10:35 +0200 Subject: [Openstack-docs] [Heat][Documentation] Heat template documentation In-Reply-To: <CAD0KtVF6qnO4-Kd7ELxJZU53r7jtTSv7mCJG3ZVyJu-C+LxtYA@mail.gmail.com> References: <90d4482bcd0b7a52c7262631ffd3baef@objectif-libre.com> <CAD0KtVF6qnO4-Kd7ELxJZU53r7jtTSv7mCJG3ZVyJu-C+LxtYA@mail.gmail.com> Message-ID: <37903930f5456fa6f09066fe41cce960@objectif-libre.com> Le 2014-05-16 17:13, Anne Gentle a ?crit?: > On Thu, May 15, 2014 at 10:34 AM, Gauvain Pocentek > <gauvain.pocentek at objectif-libre.com> wrote: > >> Hello, >> >> This mail probably mainly concerns the doc team, but I guess that the >> heat team wants to know what's going on. >> >> We've shortly discussed the state of heat documentation with Anne >> Gentle and Andreas Jaeger yesterday, and I'd like to share what we >> think would be nice to do. >> >> Currently we only have a small section in the user guide that >> describes how to start a stack, but nothing documenting how to write >> templates. The heat developer doc provides a good reference, but I >> think it's not easy to use to get started. >> >> So the idea is to add an "OpenStack Orchestration" chapter in the >> user guide that would document how to use a cloud with heat, and how >> to write templates. >> >> I've drafted a spec to keep track of this at [0]. > > I'd like to experiment a bit with converting the End User Guide to an > easier markup to enable more contributors to it. Perhaps bringing in > Orchestration is a good point to do this, plus it may help address the > auto-generation Steve mentions.? > > The loss would be the single sourcing of the End User Guide and Admin > User Guide as well as loss of PDF output and loss of translation. If > these losses are worthwhile for easier maintenance and to encourage > contributions from more cloud consumers, then I'd like to try an > experiment with it. Using RST would probably make it easier to import/include the developers' documentation. But I'm not sure we can afford to loose the features you mention. Translations for the user guides are very important I think. How would we review changes made in "external" repositories? The user guides are continuously published, this means that a change done in the heat/docs/ dir would quite quickly land on the webserver without a doc team review. I completely trust the developers, but I'm not sure that this is the way to go. > > The experiment would be to have a new repo set up, > openstack/user-guide and use the docs-core team as reviewers on it. > Convert the End User Guide from DocBook to RST and build with Sphinx. > Use the oslosphinx tempate for output. But what I don't know is if > it's possible to build the automated output outside of the > openstack/heat repo, does anyone have interest in doing a proof of > concept on this?? I'm not sure that this is possible, but I'm no RST expert. > I'd also like input on the loss of features I'm describing above. Is > this worth experimenting with? Starting this new book sounds like a lot of work. Right now I'm not convinced it's worth it. Gauvain From anne at openstack.org Sat May 17 03:03:38 2014 From: anne at openstack.org (Anne Gentle) Date: Fri, 16 May 2014 22:03:38 -0500 Subject: [Openstack-docs] Searching for docs reviews in Gerrit Message-ID: <CAD0KtVEzm1_mLY6xGU+Q+8AciKfDS7t5SVEksmk2qFrKd_VAow@mail.gmail.com> A great question came out of a docs session today and I wanted to post this hint/tip here, and also ask a question. Gerrit has documentation that describes how to use regular expressions to search for specific reviews. See https://review.openstack.org/Documentation/user-search.html One that I've found handy for docs reviews is: file:^*REGEX* Matches any change where REGEX matches a file that was affected by the change. The regular expression pattern must start with ^. For example, to match all XML files usefile:^.*\.xml$. The dk.brics.automaton library<http://www.brics.dk/automaton/> is used for the evaluation of such patterns. The ^ required at the beginning of the regular expression not only denotes a regular expression, but it also has the usual meaning of anchoring the match to the start of the string. To match all Java files, use file:^.*\.java. The entire regular expression pattern, including the ^ character, should be double quoted when using more complex construction (like ones using a bracket expression). For example, to match all XML files named like *name1.xml*, *name2.xml*, and *name3.xml* use file:"^name[1-3].xml". For example, if you want to review all RST files that are edited in a repo, log into review.openstack.org, then go to Settings > Watched Projects. Then, on a particular project's repo, look for file:^.*\.rst. One example I'd like to know about -- is it possible to watch all changes to the Networking chapter in the Cloud Admin Guide in the openstack/openstack-manuals repo? This particular search didn't work for me: file:"section_networking-adv-config.xml" project:openstack/openstack-manuals nor does: file:"docs/admin-guide-cloud/networking/section_networking-adv-config.xml" project:openstack/openstack-manuals Any more ideas for focusing on doc reviews in specialty areas? Thanks, Anne -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140516/dd6c4e9d/attachment-0001.html> From aj at suse.com Sat May 17 03:27:27 2014 From: aj at suse.com (Andreas Jaeger) Date: Sat, 17 May 2014 05:27:27 +0200 Subject: [Openstack-docs] Policy for approving backports In-Reply-To: <fec80c3953ae843bbee513bd22d8a1c8@objectif-libre.com> References: <e8ae767f5c80279bb44a1507828e3116@objectif-libre.com> <5374E1B5.1090004@openstack.org> <5374E67C.40504@suse.com> <fec80c3953ae843bbee513bd22d8a1c8@objectif-libre.com> Message-ID: <5376D71F.6080806@suse.com> On 05/16/2014 04:05 PM, Gauvain Pocentek wrote: > Le 2014-05-15 18:08, Andreas Jaeger a ?crit : >> On 05/15/2014 11:48 AM, Tom Fifield wrote: >>> On 15/05/14 11:40, Gauvain Pocentek wrote: >>>> Hello, >>>> >>>> I guess I should have asked this during this morning's doc session at >>>> the summit, but I hadn't had real coffee yet (only decaf!). >>>> >>>> How do we handle backports reviews? Is one +2 enough (that's what >>>> Andreas used to do during the post havana backport storm)? Is self >>>> approval a valid option? >>>> >>>> I'd like to hear what you guys think. >>> >>> IMO: one sanity-check +2 from someone who is not the submitter >> >> Agreed. >> >> Also, backports should not be edited, if there are problems noticed, we >> should do a patch for master to fix those and backport that one, > > Sounds good to me. Thanks for the feedback! > > I guess that we could add that info to the upcoming review guide :) Sure, go ahead ;) But first let Anne approve the blueprint and get the first patch in that creates it ;) Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Sat May 17 16:55:07 2014 From: anne at openstack.org (Anne Gentle) Date: Sat, 17 May 2014 11:55:07 -0500 Subject: [Openstack-docs] Policy for approving backports In-Reply-To: <5374E67C.40504@suse.com> References: <e8ae767f5c80279bb44a1507828e3116@objectif-libre.com> <5374E1B5.1090004@openstack.org> <5374E67C.40504@suse.com> Message-ID: <CAD0KtVEhu6fJhdB07hDTanNfD+kVgGxTb-7S-HFoqWOuNoq0dw@mail.gmail.com> On Thu, May 15, 2014 at 11:08 AM, Andreas Jaeger <aj at suse.com> wrote: > On 05/15/2014 11:48 AM, Tom Fifield wrote: > > On 15/05/14 11:40, Gauvain Pocentek wrote: > >> Hello, > >> > >> I guess I should have asked this during this morning's doc session at > >> the summit, but I hadn't had real coffee yet (only decaf!). > >> > >> How do we handle backports reviews? Is one +2 enough (that's what > >> Andreas used to do during the post havana backport storm)? Is self > >> approval a valid option? > >> > >> I'd like to hear what you guys think. > > > > IMO: one sanity-check +2 from someone who is not the submitter > > Yep, agree with this as well (and I know I need it!) Where's the blueprint? I'm fine with just documenting this standard in the review guide. Anne > Agreed. > > Also, backports should not be edited, if there are problems noticed, we > should do a patch for master to fix those and backport that one, > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140517/c808329f/attachment.html> From annegentle at gmail.com Sat May 17 18:10:21 2014 From: annegentle at gmail.com (annegentle at gmail.com) Date: Sat, 17 May 2014 18:10:21 +0000 Subject: [Openstack-docs] Google Analytics: Pages Message-ID: <089e0111b99a7c5ee204f99c7130@google.com> For your perusal, the Pages report from Google Analytics is attached, showing the Pageviews, Bounce Rate, %Exit and more for pages on the http://docs.openstack.org site. Anne ---------------------------------------- This is a report email from Google Analytics. You received this email because annegentle at gmail.com requested this report be sent to you. If you would like to opt out of emails from this user, go to https://www.google.com/analytics/web/optout?token=52rfpUYBAAA.PXlfi93zuPDcITpdeJeHPjn5Jt8i6hAKPw6q4lsZdoKd9lHq5BdZkEkA1djaWc-TU_un2AulG82SCEmJ7v5Dol5Id1PGOwOxv8TFlzhhjPQ.L3lSrep-0fqxiQ_TAuFaFg&email=openstack-docs%40lists.openstack.org&hl=en_US -------------- next part -------------- A non-text attachment was scrubbed... Name: Analytics Docs Pages 20140417-20140516.pdf Type: application/pdf Size: 108704 bytes Desc: not available URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140517/2f533ba3/attachment-0001.pdf> From mkassawara at gmail.com Sun May 18 01:32:24 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Sat, 17 May 2014 19:32:24 -0600 Subject: [Openstack-docs] Improvements to the Installation Guide Message-ID: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> I created a blueprint for improvements to the Installation Guide. https://blueprints.launchpad.net/openstack-manuals/+spec/installation-guide-improvements The suggested changes currently live in an Etherpad. https://etherpad.openstack.org/p/installation-guide-audit The blueprint needs a specification. Shall I organize our ideas from the Etherpad and add them to a Wiki page with suggested priorities? I'm also curious how we plan to track and divide up the work. I'm thinking about using bugs... either a single one similar to how we handled the Installation Guide networking improvements, or one per chapter, or... other suggestions? -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140517/c29dd16e/attachment.html> From mkassawara at gmail.com Sun May 18 03:22:15 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Sat, 17 May 2014 21:22:15 -0600 Subject: [Openstack-docs] Documentation Guide Message-ID: <CABA+jQos25_TaHw4PVpQJOd7KWbvrr46ypRHQO44AxrkoG3EFg@mail.gmail.com> Similar to the Installation Guide improvements, how shall we handle the Documentation Guide? https://blueprints.launchpad.net/openstack-manuals/+spec/docs-guide -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140517/21c03ed2/attachment.html> From anne at openstack.org Sun May 18 03:46:11 2014 From: anne at openstack.org (Anne Gentle) Date: Sat, 17 May 2014 22:46:11 -0500 Subject: [Openstack-docs] Improvements to the Installation Guide In-Reply-To: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> References: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> Message-ID: <CAD0KtVFTcL-wREXNScM6haHheEKUJHADh_FLPxi0afYzf6mUAA@mail.gmail.com> On Sat, May 17, 2014 at 8:32 PM, Matt Kassawara <mkassawara at gmail.com>wrote: > I created a blueprint for improvements to the Installation Guide. > > > https://blueprints.launchpad.net/openstack-manuals/+spec/installation-guide-improvements > > The suggested changes currently live in an Etherpad. > > https://etherpad.openstack.org/p/installation-guide-audit > > The blueprint needs a specification. Shall I organize our ideas from the > Etherpad and add them to a Wiki page with suggested priorities? > Yep, that's how it works -- see the link "Set the URL for this specification" on that page, we set that to be a wiki page. A good example is https://wiki.openstack.org/wiki/Blueprint-restructure-documentation > I'm also curious how we plan to track and divide up the work. I'm thinking > about using bugs... either a single one similar to how we handled the > Installation Guide networking improvements, or one per chapter, or... other > suggestions? > The blueprint and a detailed wiki page should be enough to track the work rather than individual bugs. Blueprints are typically assigned to a single person, but that person can track for a team. I'd rather the blueprint in this case incorporate all the "bugs" the audit found. Thanks for organizing! Anne > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140517/f5ca2126/attachment.html> From anne at openstack.org Sun May 18 03:48:41 2014 From: anne at openstack.org (Anne Gentle) Date: Sat, 17 May 2014 22:48:41 -0500 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <CABA+jQos25_TaHw4PVpQJOd7KWbvrr46ypRHQO44AxrkoG3EFg@mail.gmail.com> References: <CABA+jQos25_TaHw4PVpQJOd7KWbvrr46ypRHQO44AxrkoG3EFg@mail.gmail.com> Message-ID: <CAD0KtVEkWzdUjmGuaXL+shTb7n9u4hgoEWV_pv5pPpZjrxot9g@mail.gmail.com> On Sat, May 17, 2014 at 10:22 PM, Matt Kassawara <mkassawara at gmail.com>wrote: > Similar to the Installation Guide improvements, how shall we handle the > Documentation Guide? > > https://blueprints.launchpad.net/openstack-manuals/+spec/docs-guide > > In this case, Diane has a start for a docs guide that we may be able to reuse. I'll approve once she has a chance to take a look and see what's re-usable. I'd like a wiki page linked with "Set the URL for this specification" prior to approving this blueprint that contains this analysis. Thanks, Anne > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140517/91e0a471/attachment.html> From berendt at b1-systems.de Sun May 18 09:51:03 2014 From: berendt at b1-systems.de (Christian Berendt) Date: Sun, 18 May 2014 11:51:03 +0200 Subject: [Openstack-docs] Improvements to the Installation Guide In-Reply-To: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> References: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> Message-ID: <53788287.4020203@b1-systems.de> On 05/18/2014 03:32 AM, Matt Kassawara wrote: > The suggested changes currently live in an Etherpad. > > https://etherpad.openstack.org/p/installation-guide-audit Will there be bugs opened first for all the changes mentioned in the Etherpad? I would like to take over some changes but I'm not sure who is responsible for the several changes at the moment and if there is somebody already assigned. Christian. -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 From mkassawara at gmail.com Sun May 18 13:00:08 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Sun, 18 May 2014 07:00:08 -0600 Subject: [Openstack-docs] Improvements to the Installation Guide In-Reply-To: <53788287.4020203@b1-systems.de> References: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> <53788287.4020203@b1-systems.de> Message-ID: <CABA+jQo1HwmujP_BL4W7AkdUs=5Zr6xDSUGD_z477UXqrxXdWw@mail.gmail.com> I suppose we can use the "work items" section in the blueprint or note activities on the Wiki page. On Sun, May 18, 2014 at 3:51 AM, Christian Berendt <berendt at b1-systems.de>wrote: > On 05/18/2014 03:32 AM, Matt Kassawara wrote: > > The suggested changes currently live in an Etherpad. > > > > https://etherpad.openstack.org/p/installation-guide-audit > > Will there be bugs opened first for all the changes mentioned in the > Etherpad? I would like to take over some changes but I'm not sure who is > responsible for the several changes at the moment and if there is > somebody already assigned. > > Christian. > > -- > Christian Berendt > Cloud Computing Solution Architect > Mail: berendt at b1-systems.de > > B1 Systems GmbH > Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de > GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140518/eac10bff/attachment.html> From diane.fleming at RACKSPACE.COM Sun May 18 14:59:26 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Sun, 18 May 2014 14:59:26 +0000 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <CAD0KtVEkWzdUjmGuaXL+shTb7n9u4hgoEWV_pv5pPpZjrxot9g@mail.gmail.com> Message-ID: <CF9E329D.2D4C0%diane.fleming@rackspace.com> Hey Anne, The existing Writers Guide is broken at the moment (meaning, it's not publishing correctly to http://docs.rackspace.com/writers-guide/content/<http://docs.rackspace.com/writers-guide/content/ch_wadl.html> - David C is looking into that. However, I'm thinking that I should convert this to a CONTRIBUTING.rst document in the openstack/openstack-manuals repo, similar to what devs do. Long wikis aren't very useable (IMO). People tend to look for this information in github now. I could also write an API-specific CONTRIBUTING.rst in the openstack/api-site repo. Also, the Rackspace writers have asked me to do something similar for the Rackspace version of this guide. Anne, you can see a copy of the guide here (it's Rackspace internal so others probably can't see it, sorry) http://docs-internal.rackspace.com/process/api/v1/writers-guide/content/ch_preface.html Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com From: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>> Date: Saturday, May 17, 2014 10:48 PM To: Matt Kassawara <mkassawara at gmail.com<mailto:mkassawara at gmail.com>> Cc: "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>> Subject: Re: [Openstack-docs] Documentation Guide On Sat, May 17, 2014 at 10:22 PM, Matt Kassawara <mkassawara at gmail.com<mailto:mkassawara at gmail.com>> wrote: Similar to the Installation Guide improvements, how shall we handle the Documentation Guide? https://blueprints.launchpad.net/openstack-manuals/+spec/docs-guide In this case, Diane has a start for a docs guide that we may be able to reuse. I'll approve once she has a chance to take a look and see what's re-usable. I'd like a wiki page linked with "Set the URL for this specification" prior to approving this blueprint that contains this analysis. Thanks, Anne _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140518/158d79e9/attachment.html> From diane.fleming at RACKSPACE.COM Sun May 18 15:16:12 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Sun, 18 May 2014 15:16:12 +0000 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <CF9E329D.2D4C0%diane.fleming@rackspace.com> Message-ID: <CF9E3883.2D4DA%diane.fleming@rackspace.com> The current Docs guide (Writers Guide) is now up http://docs.rackspace.com/writers-guide/content/ch_preface.html Depending on what the consensus is, I can either move the source files to the repo created by Andreas, or convert to CONTRIBUTING.rst files ? one for openstack-manuals and one for api-site. (I prefer the latter solution). Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com From: Diane Fleming <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>> Date: Sunday, May 18, 2014 9:59 AM To: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>>, Matt Kassawara <mkassawara at gmail.com<mailto:mkassawara at gmail.com>> Cc: "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>> Subject: Re: [Openstack-docs] Documentation Guide Hey Anne, The existing Writers Guide is broken at the moment (meaning, it's not publishing correctly to http://docs.rackspace.com/writers-guide/content/<http://docs.rackspace.com/writers-guide/content/ch_wadl.html> - David C is looking into that. However, I'm thinking that I should convert this to a CONTRIBUTING.rst document in the openstack/openstack-manuals repo, similar to what devs do. Long wikis aren't very useable (IMO). People tend to look for this information in github now. I could also write an API-specific CONTRIBUTING.rst in the openstack/api-site repo. Also, the Rackspace writers have asked me to do something similar for the Rackspace version of this guide. Anne, you can see a copy of the guide here (it's Rackspace internal so others probably can't see it, sorry) http://docs-internal.rackspace.com/process/api/v1/writers-guide/content/ch_preface.html Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com> Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com<mailto:diane.fleming at gmail.com> From: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>> Date: Saturday, May 17, 2014 10:48 PM To: Matt Kassawara <mkassawara at gmail.com<mailto:mkassawara at gmail.com>> Cc: "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>> Subject: Re: [Openstack-docs] Documentation Guide On Sat, May 17, 2014 at 10:22 PM, Matt Kassawara <mkassawara at gmail.com<mailto:mkassawara at gmail.com>> wrote: Similar to the Installation Guide improvements, how shall we handle the Documentation Guide? https://blueprints.launchpad.net/openstack-manuals/+spec/docs-guide In this case, Diane has a start for a docs guide that we may be able to reuse. I'll approve once she has a chance to take a look and see what's re-usable. I'd like a wiki page linked with "Set the URL for this specification" prior to approving this blueprint that contains this analysis. Thanks, Anne _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140518/7f6bfabe/attachment-0001.html> From aj at suse.com Sun May 18 17:56:33 2014 From: aj at suse.com (Andreas Jaeger) Date: Sun, 18 May 2014 19:56:33 +0200 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <CF9E3883.2D4DA%diane.fleming@rackspace.com> References: <CF9E3883.2D4DA%diane.fleming@rackspace.com> Message-ID: <5378F451.9070607@suse.com> On 05/18/2014 05:16 PM, Diane Fleming wrote: > The current Docs guide (Writers Guide) is now up > > http://docs.rackspace.com/writers-guide/content/ch_preface.html Not reachable for me. > Depending on what the consensus is, I can either move the source files > to the repo created by Andreas, or convert to CONTRIBUTING.rst files ? > one for openstack-manuals and one for api-site. > > (I prefer the latter solution). The idea we had at the summit was to move over from the wiki the Conventions and processes - so to have a single place as reference for all contributors, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From diane.fleming at RACKSPACE.COM Sun May 18 19:57:43 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Sun, 18 May 2014 19:57:43 +0000 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <5378F451.9070607@suse.com> References: <CF9E3883.2D4DA%diane.fleming@rackspace.com>, <5378F451.9070607@suse.com> Message-ID: <2D4B651C-AC9E-4744-8B8B-7EB558C7505B@RACKSPACE.COM> Andreas, that link should be reachable for you. Yes, good idea to move conventions to one place. I am fine if it is docbook but would prefer Github repo as i said. Sent from my iPhone > On May 18, 2014, at 12:56 PM, "Andreas Jaeger" <aj at suse.com> wrote: > >> On 05/18/2014 05:16 PM, Diane Fleming wrote: >> The current Docs guide (Writers Guide) is now up >> >> http://docs.rackspace.com/writers-guide/content/ch_preface.html > > Not reachable for me. > >> Depending on what the consensus is, I can either move the source files >> to the repo created by Andreas, or convert to CONTRIBUTING.rst files ? >> one for openstack-manuals and one for api-site. >> >> (I prefer the latter solution). > > The idea we had at the summit was to move over from the wiki the > Conventions and processes - so to have a single place as reference for > all contributors, > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Sun May 18 21:15:51 2014 From: anne at openstack.org (Anne Gentle) Date: Sun, 18 May 2014 16:15:51 -0500 Subject: [Openstack-docs] Improvements to the Installation Guide In-Reply-To: <CABA+jQo1HwmujP_BL4W7AkdUs=5Zr6xDSUGD_z477UXqrxXdWw@mail.gmail.com> References: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> <53788287.4020203@b1-systems.de> <CABA+jQo1HwmujP_BL4W7AkdUs=5Zr6xDSUGD_z477UXqrxXdWw@mail.gmail.com> Message-ID: <CAD0KtVE+BEpom3DSwE_h-0XtCq3UwgUhbE8bgo9y731g0mQL_Q@mail.gmail.com> On Sun, May 18, 2014 at 8:00 AM, Matt Kassawara <mkassawara at gmail.com>wrote: > I suppose we can use the "work items" section in the blueprint or note > activities on the Wiki page. > If you're all willing to work this way, I think it helps us know the "quality" of our docs set by tracking bugs as defect or inaccuracy rather than reorg or gap-filling. What do you think? Is it work-able to track on the wiki page? Let's also talk about how we can make a roadmap-per-book workable while still not causing duplication of effort. My original thinking is that you'd update the roadmap with your patch, but now I realize 2 people could work on a roadmap item at once without knowing the other is doing the same thing. Thoughts? Thanks, Anne > > On Sun, May 18, 2014 at 3:51 AM, Christian Berendt <berendt at b1-systems.de>wrote: > >> On 05/18/2014 03:32 AM, Matt Kassawara wrote: >> > The suggested changes currently live in an Etherpad. >> > >> > https://etherpad.openstack.org/p/installation-guide-audit >> >> Will there be bugs opened first for all the changes mentioned in the >> Etherpad? I would like to take over some changes but I'm not sure who is >> responsible for the several changes at the moment and if there is >> somebody already assigned. >> >> Christian. >> >> -- >> Christian Berendt >> Cloud Computing Solution Architect >> Mail: berendt at b1-systems.de >> >> B1 Systems GmbH >> Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de >> GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140518/55e7850d/attachment.html> From anne at openstack.org Sun May 18 21:16:57 2014 From: anne at openstack.org (Anne Gentle) Date: Sun, 18 May 2014 16:16:57 -0500 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <2D4B651C-AC9E-4744-8B8B-7EB558C7505B@RACKSPACE.COM> References: <CF9E3883.2D4DA%diane.fleming@rackspace.com> <5378F451.9070607@suse.com> <2D4B651C-AC9E-4744-8B8B-7EB558C7505B@RACKSPACE.COM> Message-ID: <CAD0KtVHeqz=uMJpHhAY5XVVmcTm2UYXzE-rDhV97ihN_gXdQ-g@mail.gmail.com> Hey Diane, yep that's the one I was thinking of, but it 404s on the rackspace.com site. Let's make it something that doesn't have to be published but just lives in the repo. Anne On Sun, May 18, 2014 at 2:57 PM, Diane Fleming <diane.fleming at rackspace.com>wrote: > Andreas, that link should be reachable for you. Yes, good idea to move > conventions to one place. I am fine if it is docbook but would prefer > Github repo as i said. > > Sent from my iPhone > > > On May 18, 2014, at 12:56 PM, "Andreas Jaeger" <aj at suse.com> wrote: > > > >> On 05/18/2014 05:16 PM, Diane Fleming wrote: > >> The current Docs guide (Writers Guide) is now up > >> > >> http://docs.rackspace.com/writers-guide/content/ch_preface.html > > > > Not reachable for me. > > > >> Depending on what the consensus is, I can either move the source files > >> to the repo created by Andreas, or convert to CONTRIBUTING.rst files ? > >> one for openstack-manuals and one for api-site. > >> > >> (I prefer the latter solution). > > > > The idea we had at the summit was to move over from the wiki the > > Conventions and processes - so to have a single place as reference for > > all contributors, > > > > Andreas > > -- > > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140518/d76a047f/attachment.html> From mkassawara at gmail.com Sun May 18 23:02:04 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Sun, 18 May 2014 17:02:04 -0600 Subject: [Openstack-docs] Improvements to the Installation Guide In-Reply-To: <CAD0KtVE+BEpom3DSwE_h-0XtCq3UwgUhbE8bgo9y731g0mQL_Q@mail.gmail.com> References: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> <53788287.4020203@b1-systems.de> <CABA+jQo1HwmujP_BL4W7AkdUs=5Zr6xDSUGD_z477UXqrxXdWw@mail.gmail.com> <CAD0KtVE+BEpom3DSwE_h-0XtCq3UwgUhbE8bgo9y731g0mQL_Q@mail.gmail.com> Message-ID: <CABA+jQpeS+Osy3aKdUG=pTuZN6V-v0Wh52GA52AKX=ycVsMnrQ@mail.gmail.com> Any centralized place that we can agree upon to track activity works for me... wiki, etherpad, bug, etc. This also applies to roadmaps. I almost wish we could extend blueprints to handle roadmaps... essentially "living" blueprints that remain open and flexible for the duration of a project. On Sun, May 18, 2014 at 3:15 PM, Anne Gentle <anne at openstack.org> wrote: > > > > On Sun, May 18, 2014 at 8:00 AM, Matt Kassawara <mkassawara at gmail.com>wrote: > >> I suppose we can use the "work items" section in the blueprint or note >> activities on the Wiki page. >> > > If you're all willing to work this way, I think it helps us know the > "quality" of our docs set by tracking bugs as defect or inaccuracy rather > than reorg or gap-filling. What do you think? Is it work-able to track on > the wiki page? > > Let's also talk about how we can make a roadmap-per-book workable while > still not causing duplication of effort. My original thinking is that you'd > update the roadmap with your patch, but now I realize 2 people could work > on a roadmap item at once without knowing the other is doing the same > thing. Thoughts? > Thanks, > Anne > > >> >> On Sun, May 18, 2014 at 3:51 AM, Christian Berendt <berendt at b1-systems.de >> > wrote: >> >>> On 05/18/2014 03:32 AM, Matt Kassawara wrote: >>> > The suggested changes currently live in an Etherpad. >>> > >>> > https://etherpad.openstack.org/p/installation-guide-audit >>> >>> Will there be bugs opened first for all the changes mentioned in the >>> Etherpad? I would like to take over some changes but I'm not sure who is >>> responsible for the several changes at the moment and if there is >>> somebody already assigned. >>> >>> Christian. >>> >>> -- >>> Christian Berendt >>> Cloud Computing Solution Architect >>> Mail: berendt at b1-systems.de >>> >>> B1 Systems GmbH >>> Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de >>> GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 >>> >>> _______________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.openstack.org >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>> >> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140518/a338c999/attachment-0001.html> From yorik.sar at gmail.com Mon May 19 04:31:32 2014 From: yorik.sar at gmail.com (Yuriy Taraday) Date: Mon, 19 May 2014 08:31:32 +0400 Subject: [Openstack-docs] [openstack-dev] Searching for docs reviews in Gerrit In-Reply-To: <CAD0KtVEzm1_mLY6xGU+Q+8AciKfDS7t5SVEksmk2qFrKd_VAow@mail.gmail.com> References: <CAD0KtVEzm1_mLY6xGU+Q+8AciKfDS7t5SVEksmk2qFrKd_VAow@mail.gmail.com> Message-ID: <CABocrW4nhsP9MKiBhUS_Nyf7AsHWr2ZoV=ysmBbZWTU+ceUUYw@mail.gmail.com> Hello, Anne. On Sat, May 17, 2014 at 7:03 AM, Anne Gentle <anne at openstack.org> wrote: > file:"section_networking-adv-config.xml" > project:openstack/openstack-manuals > As it's stated in the manual: "The regular expression pattern must start with ^." Meaning that it'll always look only for files whose paths start with string matching this regex not just include them. > nor does: > file:"docs/admin-guide-cloud/networking/section_networking-adv-config.xml" > project:openstack/openstack-manuals > You've misspelled the first dir name - it's "doc" and it's working. -- Kind regards, Yuriy. -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140519/bf2deaf7/attachment.html> From aj at suse.com Mon May 19 08:26:28 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 19 May 2014 10:26:28 +0200 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <2D4B651C-AC9E-4744-8B8B-7EB558C7505B@RACKSPACE.COM> References: <CF9E3883.2D4DA%diane.fleming@rackspace.com>, <5378F451.9070607@suse.com> <2D4B651C-AC9E-4744-8B8B-7EB558C7505B@RACKSPACE.COM> Message-ID: <5379C034.5040808@suse.com> On 05/18/2014 09:57 PM, Diane Fleming wrote: > Andreas, that link should be reachable for you. Yes, good idea to move conventions to one place. I am fine if it is docbook but would prefer Github repo as i said. The link does not work. So, you want to have it in a *separate* repo? Matt and myself wanted to have it as part of openstack-manuals - just as a separate guide/directory. Andreas > Sent from my iPhone > >> On May 18, 2014, at 12:56 PM, "Andreas Jaeger" <aj at suse.com> wrote: >> >>> On 05/18/2014 05:16 PM, Diane Fleming wrote: >>> The current Docs guide (Writers Guide) is now up >>> >>> http://docs.rackspace.com/writers-guide/content/ch_preface.html >> >> Not reachable for me. >> >>> Depending on what the consensus is, I can either move the source files >>> to the repo created by Andreas, or convert to CONTRIBUTING.rst files ? >>> one for openstack-manuals and one for api-site. >>> >>> (I prefer the latter solution). >> >> The idea we had at the summit was to move over from the wiki the >> Conventions and processes - so to have a single place as reference for >> all contributors, >> >> Andreas >> -- >> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany >> GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Mon May 19 08:27:08 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 19 May 2014 10:27:08 +0200 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <CAD0KtVHeqz=uMJpHhAY5XVVmcTm2UYXzE-rDhV97ihN_gXdQ-g@mail.gmail.com> References: <CF9E3883.2D4DA%diane.fleming@rackspace.com> <5378F451.9070607@suse.com> <2D4B651C-AC9E-4744-8B8B-7EB558C7505B@RACKSPACE.COM> <CAD0KtVHeqz=uMJpHhAY5XVVmcTm2UYXzE-rDhV97ihN_gXdQ-g@mail.gmail.com> Message-ID: <5379C05C.4020304@suse.com> On 05/18/2014 11:16 PM, Anne Gentle wrote: > Hey Diane, yep that's the one I was thinking of, but it 404s on the > rackspace.com <http://rackspace.com> site. > > Let's make it something that doesn't have to be published but just lives > in the repo. Anne, if we move conventions and process in it, we should publish the content, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From diane.fleming at RACKSPACE.COM Mon May 19 11:39:07 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Mon, 19 May 2014 11:39:07 +0000 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <5379C05C.4020304@suse.com> References: <CF9E3883.2D4DA%diane.fleming@rackspace.com> <5378F451.9070607@suse.com> <2D4B651C-AC9E-4744-8B8B-7EB558C7505B@RACKSPACE.COM> <CAD0KtVHeqz=uMJpHhAY5XVVmcTm2UYXzE-rDhV97ihN_gXdQ-g@mail.gmail.com>, <5379C05C.4020304@suse.com> Message-ID: <B92BB4DE-C27F-4D6D-9287-A4E4C6A5C408@RACKSPACE.COM> Why do we need to publish it if we move it to something like CONTRIBUTING.rst, which would be viewable if you open the file while in the repo? That's how dev does it. Sent from my iPhone > On May 19, 2014, at 3:27 AM, "Andreas Jaeger" <aj at suse.com> wrote: > >> On 05/18/2014 11:16 PM, Anne Gentle wrote: >> Hey Diane, yep that's the one I was thinking of, but it 404s on the >> rackspace.com <http://rackspace.com> site. >> >> Let's make it something that doesn't have to be published but just lives >> in the repo. > > Anne, if we move conventions and process in it, we should publish the > content, > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Mon May 19 11:55:46 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 19 May 2014 13:55:46 +0200 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <B92BB4DE-C27F-4D6D-9287-A4E4C6A5C408@RACKSPACE.COM> References: <CF9E3883.2D4DA%diane.fleming@rackspace.com> <5378F451.9070607@suse.com> <2D4B651C-AC9E-4744-8B8B-7EB558C7505B@RACKSPACE.COM> <CAD0KtVHeqz=uMJpHhAY5XVVmcTm2UYXzE-rDhV97ihN_gXdQ-g@mail.gmail.com>, <5379C05C.4020304@suse.com> <B92BB4DE-C27F-4D6D-9287-A4E4C6A5C408@RACKSPACE.COM> Message-ID: <5379F142.3020808@suse.com> On 05/19/2014 01:39 PM, Diane Fleming wrote: > Why do we need to publish it if we move it to something like CONTRIBUTING.rst, which would be viewable if you open the file while in the repo? That's how dev does it. The idea was to have a document that includes Conventions, processes - and we want to be able to give a URL during review to point out a issue. Best would be a quasi permanent URL and not a link to some line in a document that changes... Andreas > Sent from my iPhone > >> On May 19, 2014, at 3:27 AM, "Andreas Jaeger" <aj at suse.com> wrote: >> >>> On 05/18/2014 11:16 PM, Anne Gentle wrote: >>> Hey Diane, yep that's the one I was thinking of, but it 404s on the >>> rackspace.com <http://rackspace.com> site. >>> >>> Let's make it something that doesn't have to be published but just lives >>> in the repo. >> >> Anne, if we move conventions and process in it, we should publish the >> content, >> >> Andreas >> -- >> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany >> GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Mon May 19 17:17:27 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 19 May 2014 19:17:27 +0200 Subject: [Openstack-docs] Translation gate for doc jobs In-Reply-To: <5375FE39.20904@openstack.org> References: <5375284F.3030208@suse.com> <5375FE39.20904@openstack.org> Message-ID: <537A3CA7.8080100@suse.com> On 05/16/2014 02:02 PM, Tom Fifield wrote: > On 15/05/14 16:49, Andreas Jaeger wrote: >> Inspired by some discussions here at the summit, I'd like to setup some >> translation gate for jobs. >> >> Patch https://review.openstack.org/93526 (merged) sets up a test that >> can be invoked with "tox -e checklang" which builds all "supported" manuals. >> >> I propose the following: >> >> * Setup checking/gating jobs that runs this test and mark it as non-voting. >> * Create policy on how to handle failures. >> >> Proposed policy: >> * We only gate on manual/language combinations that are translated >> sufficiently. Right now that's for openstack-manuals Japanese with the >> Security Guide, HA Guide and Install Guides only. >> * If an import from transifex fails, creates a failure, we do not >> approve the import. >> * If any other patch fails, the failure might get ignored. >> * In any case of failure, let's send an email to the openstack-i18n >> mailing list asking them to investigate and fix. >> >> What do you think? > > Good, but I'd prefer the creation of a bug in openstack-i18n on > launchpad, instead of a mailing list post. This way people who are > interested in fixing such things can get notified by email (through bug > tracker subscriptions), and the mailing list is kept clear for people > who just want to translate things and participate in the community in > other ways :) fine with me. I'll document this in the wiki once the job is in, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Mon May 19 17:21:21 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 19 May 2014 19:21:21 +0200 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <CAD0KtVEkWzdUjmGuaXL+shTb7n9u4hgoEWV_pv5pPpZjrxot9g@mail.gmail.com> References: <CABA+jQos25_TaHw4PVpQJOd7KWbvrr46ypRHQO44AxrkoG3EFg@mail.gmail.com> <CAD0KtVEkWzdUjmGuaXL+shTb7n9u4hgoEWV_pv5pPpZjrxot9g@mail.gmail.com> Message-ID: <537A3D91.1060006@suse.com> On 05/18/2014 05:48 AM, Anne Gentle wrote: > > > > On Sat, May 17, 2014 at 10:22 PM, Matt Kassawara <mkassawara at gmail.com > <mailto:mkassawara at gmail.com>> wrote: > > Similar to the Installation Guide improvements, how shall we handle > the Documentation Guide? > > https://blueprints.launchpad.net/openstack-manuals/+spec/docs-guide > > > In this case, Diane has a start for a docs guide that we may be able to > reuse. I'll approve once she has a chance to take a look and see what's > re-usable. I'd like a wiki page linked with "Set the URL for this > specification" prior to approving this blueprint that contains this > analysis. Wiki page was created by Matt and has initial content, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Mon May 19 17:27:07 2014 From: anne at openstack.org (Anne Gentle) Date: Mon, 19 May 2014 12:27:07 -0500 Subject: [Openstack-docs] Translation gate for doc jobs In-Reply-To: <5375284F.3030208@suse.com> References: <5375284F.3030208@suse.com> Message-ID: <CAD0KtVFooB-KqsYe82Rm1kQ0qVimv8asDK7Sd3COHUWBzVD6Pg@mail.gmail.com> On Thu, May 15, 2014 at 3:49 PM, Andreas Jaeger <aj at suse.com> wrote: > Inspired by some discussions here at the summit, I'd like to setup some > translation gate for jobs. > > Patch https://review.openstack.org/93526 (merged) sets up a test that > can be invoked with "tox -e checklang" which builds all "supported" > manuals. > > I propose the following: > > * Setup checking/gating jobs that runs this test and mark it as non-voting. > I'm fine with this, the only difficulty is that we need to be sure there are knowledgeable people who can troubleshoot when a job fails. > * Create policy on how to handle failures. > Yep, that's what I need, preferably a contact person. > > Proposed policy: > * We only gate on manual/language combinations that are translated > sufficiently. Right now that's for openstack-manuals Japanese with the > Security Guide, HA Guide and Install Guides only. > Is sufficiently defined as 50% translated or more? Is a single additional language at 50% enough? Just wanting some metric definition. > * If an import from transifex fails, creates a failure, we do not > approve the import. > Agreed. > * If any other patch fails, the failure might get ignored. > * In any case of failure, let's send an email to the openstack-i18n > mailing list asking them to investigate and fix. > Yep, I like the bug idea as well, seems to help with tracking and "is anyone assigned" sorts of questions. Thanks for working through this! Anne > > What do you think? > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140519/dcef8e89/attachment.html> From diane.fleming at RACKSPACE.COM Mon May 19 17:33:04 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Mon, 19 May 2014 17:33:04 +0000 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <537A3D91.1060006@suse.com> Message-ID: <CF9FAA6E.2D63B%diane.fleming@rackspace.com> Is it okay to add to that content on wiki page? Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com On 5/19/14 12:21 PM, "Andreas Jaeger" <aj at suse.com> wrote: >On 05/18/2014 05:48 AM, Anne Gentle wrote: >> >> >> >> On Sat, May 17, 2014 at 10:22 PM, Matt Kassawara <mkassawara at gmail.com >> <mailto:mkassawara at gmail.com>> wrote: >> >> Similar to the Installation Guide improvements, how shall we handle >> the Documentation Guide? >> >> https://blueprints.launchpad.net/openstack-manuals/+spec/docs-guide >> >> >> In this case, Diane has a start for a docs guide that we may be able to >> reuse. I'll approve once she has a chance to take a look and see what's >> re-usable. I'd like a wiki page linked with "Set the URL for this >> specification" prior to approving this blueprint that contains this >> analysis. > >Wiki page was created by Matt and has initial content, > >Andreas >-- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > >_______________________________________________ >Openstack-docs mailing list >Openstack-docs at lists.openstack.org >http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs From aj at suse.com Mon May 19 17:44:26 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 19 May 2014 19:44:26 +0200 Subject: [Openstack-docs] Translation gate for doc jobs In-Reply-To: <CAD0KtVFooB-KqsYe82Rm1kQ0qVimv8asDK7Sd3COHUWBzVD6Pg@mail.gmail.com> References: <5375284F.3030208@suse.com> <CAD0KtVFooB-KqsYe82Rm1kQ0qVimv8asDK7Sd3COHUWBzVD6Pg@mail.gmail.com> Message-ID: <537A42FA.4000302@suse.com> On 05/19/2014 07:27 PM, Anne Gentle wrote: > > > > On Thu, May 15, 2014 at 3:49 PM, Andreas Jaeger <aj at suse.com > <mailto:aj at suse.com>> wrote: > > Inspired by some discussions here at the summit, I'd like to setup some > translation gate for jobs. > > Patch https://review.openstack.org/93526 (merged) sets up a test that > can be invoked with "tox -e checklang" which builds all "supported" > manuals. > > I propose the following: > > * Setup checking/gating jobs that runs this test and mark it as > non-voting. > > > I'm fine with this, the only difficulty is that we need to be sure there > are knowledgeable people who can troubleshoot when a job fails. There are some as noticed with the last failure ;) > > * Create policy on how to handle failures. > > > Yep, that's what I need, preferably a contact person. With a bug report, we abstracted this ;) > > > > Proposed policy: > * We only gate on manual/language combinations that are translated > sufficiently. Right now that's for openstack-manuals Japanese with the > Security Guide, HA Guide and Install Guides only. > > > Is sufficiently defined as 50% translated or more? Is a single > additional language at 50% enough? Just wanting some metric definition. We agreed on only downloading files that are at least translated to 75% - see https://review.openstack.org/92997. So, metric is better than 75 %. > > * If an import from transifex fails, creates a failure, we do not > approve the import. > > > Agreed. > > > * If any other patch fails, the failure might get ignored. > * In any case of failure, let's send an email to the openstack-i18n > mailing list asking them to investigate and fix. > > > Yep, I like the bug idea as well, seems to help with tracking and "is > anyone assigned" sorts of questions. Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From diane.fleming at RACKSPACE.COM Mon May 19 18:19:52 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Mon, 19 May 2014 18:19:52 +0000 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <537A3D91.1060006@suse.com> Message-ID: <CF9FB551.2D664%diane.fleming@rackspace.com> Writer's guide is back up here: http://docs.rackspace.com/writers-guide/content/ch_preface.html Thank you David Cramer! Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com On 5/19/14 12:21 PM, "Andreas Jaeger" <aj at suse.com> wrote: >On 05/18/2014 05:48 AM, Anne Gentle wrote: >> >> >> >> On Sat, May 17, 2014 at 10:22 PM, Matt Kassawara <mkassawara at gmail.com >> <mailto:mkassawara at gmail.com>> wrote: >> >> Similar to the Installation Guide improvements, how shall we handle >> the Documentation Guide? >> >> https://blueprints.launchpad.net/openstack-manuals/+spec/docs-guide >> >> >> In this case, Diane has a start for a docs guide that we may be able to >> reuse. I'll approve once she has a chance to take a look and see what's >> re-usable. I'd like a wiki page linked with "Set the URL for this >> specification" prior to approving this blueprint that contains this >> analysis. > >Wiki page was created by Matt and has initial content, > >Andreas >-- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > >_______________________________________________ >Openstack-docs mailing list >Openstack-docs at lists.openstack.org >http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs From aj at suse.com Mon May 19 20:41:01 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 19 May 2014 22:41:01 +0200 Subject: [Openstack-docs] Target audience Message-ID: <537A6C5D.9090600@suse.com> We had some discussion about target audience for each guide at the OpenStack summit and Anne filed this bug: https://bugs.launchpad.net/openstack-manuals/+bug/1319394 . As a first step, I've went over all guides and categorized them according to target audience and then copied all the current abstracts together. Is the following accurate? Andreas Overview of personas/target audience: Operations Guide Cloud Administrator Guide Configuration Reference HA Guide Install Guide Security Guide Admin User Guide These guides target cloud administrators who sets up an OpenStack cloud and configures the OpenStack services. End User Guide Image Guide These guide targets users using an OpenStack cloud. CLI Reference This guide targets both cloud administrators and users using an OpenStack cloud. Not covered personas: Developer writing applications running in an OpenStack Cloud. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Detailed information - copy of current abstract: Install Guide The OpenStack? system consists of several key projects that you install separately but that work together depending on your cloud needs. These projects include Compute, Identity Service, Networking, Image Service, Block Storage, Object Storage, Telemetry, Orchestration, and Database. You can install any of these projects separately and configure them stand-alone or as connected entities. This guide shows you how to install OpenStack by using packages on openSUSE through the Open Build Service Cloud repository. Explanations of configuration options and sample configuration files are included. Operations Guide This book provides information about designing and operating OpenStack clouds. Cloud Administrator Guide OpenStack offers open source software for cloud administrators to manage and troubleshoot an OpenStack cloud. Configuration Reference This document is for system administrators who want to look up configuration options. It contains lists of configuration options available with OpenStack and uses auto-generation to generate options and the descriptions from the code for each project. It includes sample configuration files. HA Guide No abstract given. Security Guide This book provides best practices and conceptual information about securing an OpenStack cloud. Admin User Guide OpenStack is an open source cloud computing platform for public and private clouds. A series of interrelated projects deliver a cloud infrastructure solution. This guide shows OpenStack admin users how to create and manage resources in an OpenStack cloud with the OpenStack dashboard or OpenStack client commands. End User Guide OpenStack is an open-source cloud computing platform for public and private clouds. A series of interrelated projects deliver a cloud infrastructure solution. This guide shows OpenStack end users how to create and manage resources in an OpenStack cloud with the OpenStack dashboard and OpenStack client commands. Image Guide This guide describes how to obtain, create, and modify virtual machine images that are compatible with OpenStack. CLI Reference This guide documents the OpenStack command-line clients. -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From Randy_Perryman at Dell.com Mon May 19 21:43:20 2014 From: Randy_Perryman at Dell.com (Randy_Perryman at Dell.com) Date: Mon, 19 May 2014 16:43:20 -0500 Subject: [Openstack-docs] Target audience In-Reply-To: <537A6C5D.9090600@suse.com> References: <537A6C5D.9090600@suse.com> Message-ID: <FC6A4A6096337446A48E483EA34F205027142368A6@AUSX7MCPC102.AMER.DELL.COM> Hi, I like your breakdown. I propose a little more granular proposal on the Operations side. Breaking them down to Operations, Installation and Security : Operations Guide Cloud Administrator Guide Admin User Guide This guide is targeted for the day to day operations of an OpenStack cloud system ------------------------ Configuration Reference HA Guide Install Guide These guides target cloud administrators who sets up an OpenStack cloud and configures the OpenStack services. ------------------------ Security Guide This guide is targeted for the Security Administrator of a cloud team and can be referenced to harden existing OpenStack deployments or to evaluate the security controls of OpenStack cloud providers. ------------------------ -Randy P.S. I opened a bug - HA guide does not have an abstract. -----Original Message----- From: Andreas Jaeger [mailto:aj at suse.com] Sent: Monday, May 19, 2014 4:41 PM To: openstack-docs at lists.openstack.org Subject: [Openstack-docs] Target audience We had some discussion about target audience for each guide at the OpenStack summit and Anne filed this bug: https://bugs.launchpad.net/openstack-manuals/+bug/1319394 . As a first step, I've went over all guides and categorized them according to target audience and then copied all the current abstracts together. Is the following accurate? Andreas Overview of personas/target audience: Operations Guide Cloud Administrator Guide Configuration Reference HA Guide Install Guide Security Guide Admin User Guide These guides target cloud administrators who sets up an OpenStack cloud and configures the OpenStack services. End User Guide Image Guide These guide targets users using an OpenStack cloud. CLI Reference This guide targets both cloud administrators and users using an OpenStack cloud. Not covered personas: Developer writing applications running in an OpenStack Cloud. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Detailed information - copy of current abstract: Install Guide The OpenStack? system consists of several key projects that you install separately but that work together depending on your cloud needs. These projects include Compute, Identity Service, Networking, Image Service, Block Storage, Object Storage, Telemetry, Orchestration, and Database. You can install any of these projects separately and configure them stand-alone or as connected entities. This guide shows you how to install OpenStack by using packages on openSUSE through the Open Build Service Cloud repository. Explanations of configuration options and sample configuration files are included. Operations Guide This book provides information about designing and operating OpenStack clouds. Cloud Administrator Guide OpenStack offers open source software for cloud administrators to manage and troubleshoot an OpenStack cloud. Configuration Reference This document is for system administrators who want to look up configuration options. It contains lists of configuration options available with OpenStack and uses auto-generation to generate options and the descriptions from the code for each project. It includes sample configuration files. HA Guide No abstract given. Security Guide This book provides best practices and conceptual information about securing an OpenStack cloud. Admin User Guide OpenStack is an open source cloud computing platform for public and private clouds. A series of interrelated projects deliver a cloud infrastructure solution. This guide shows OpenStack admin users how to create and manage resources in an OpenStack cloud with the OpenStack dashboard or OpenStack client commands. End User Guide OpenStack is an open-source cloud computing platform for public and private clouds. A series of interrelated projects deliver a cloud infrastructure solution. This guide shows OpenStack end users how to create and manage resources in an OpenStack cloud with the OpenStack dashboard and OpenStack client commands. Image Guide This guide describes how to obtain, create, and modify virtual machine images that are compatible with OpenStack. CLI Reference This guide documents the OpenStack command-line clients. -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs From anne at openstack.org Tue May 20 05:18:16 2014 From: anne at openstack.org (Anne Gentle) Date: Tue, 20 May 2014 00:18:16 -0500 Subject: [Openstack-docs] Target audience In-Reply-To: <537A6C5D.9090600@suse.com> References: <537A6C5D.9090600@suse.com> Message-ID: <CAD0KtVHqbi84aHmu+PmmZfYZJmW918ebrHiTogfRvQSq=6e7jg@mail.gmail.com> Thanks for analyzing Andreas and Randy! I like these three simple personas below. Alice the admin Alice is an administrator who is responsible for maintaining (and securing) the OpenStack cloud installation. She has many years of experience with Linux systems administration. Darren the deployer Darren is responsible for doing the initial OpenStack deployment on the host machines. Emile the end-user Emile uses the cloud to do software development inside of the virtual machines. She uses the command-line tools because she finds it quicker than using the dashboard. To me, Emile is a useful persona because she uses user tools and developer tools -- and I do see a lot of blending across user/dev tools. Andreas, the user we haven't yet started to document for is the application devops role, the operator who would monitor applications in the cloud. They might be super specialized for monitoring of the VMs themselves. But I'm not sure whether there's a fourth persona who does planning and setup, what do you all think? Archie the architect? We also don't have to be super pattern-based, we can just write a section describing the audience for each guide. On Mon, May 19, 2014 at 3:41 PM, Andreas Jaeger <aj at suse.com> wrote: > We had some discussion about target audience for each guide at the > OpenStack summit and Anne filed this bug: > https://bugs.launchpad.net/openstack-manuals/+bug/1319394 . As a first > step, I've went over all guides and categorized them according to target > audience and then copied all the current abstracts together. Is the > following accurate? > > Andreas > > Overview of personas/target audience: > > Operations Guide > Cloud Administrator Guide > Configuration Reference > HA Guide > Install Guide > Security Guide > Admin User Guide > > These guides target cloud administrators who sets up an OpenStack > cloud and configures the OpenStack services. > > End User Guide > Image Guide > > These guide targets users using an OpenStack cloud. > > CLI Reference > > This guide targets both cloud administrators and users using an > OpenStack cloud. > > Not covered personas: > > Developer writing applications running in an OpenStack Cloud. > > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > Detailed information - copy of current abstract: > > Install Guide > > The OpenStack? system consists of several key projects that you > install separately but that work together depending on your cloud > needs. These projects include Compute, Identity Service, Networking, > Image Service, Block Storage, Object Storage, Telemetry, > Orchestration, and Database. You can install any of these projects > separately and configure them stand-alone or as connected > entities. This guide shows you how to install OpenStack by using > packages on openSUSE through the Open Build Service Cloud > repository. Explanations of configuration options and sample > configuration files are included. > > > Operations Guide > > This book provides information about designing and operating OpenStack > clouds. > > Cloud Administrator Guide > > OpenStack offers open source software for cloud administrators to > manage and troubleshoot an OpenStack cloud. > > Configuration Reference > > This document is for system administrators who want to look up > configuration options. It contains lists of configuration options > available with OpenStack and uses auto-generation to generate options > and the descriptions from the code for each project. It includes > sample configuration files. > > HA Guide > > No abstract given. > > Security Guide > > This book provides best practices and conceptual information about > securing an OpenStack cloud. > > Admin User Guide > > OpenStack is an open source cloud computing platform for public and > private clouds. A series of interrelated projects deliver a cloud > infrastructure solution. This guide shows OpenStack admin users how to > create and manage resources in an OpenStack cloud with the OpenStack > dashboard or OpenStack client commands. > > > End User Guide > > OpenStack is an open-source cloud computing platform for public and > private clouds. A series of interrelated projects deliver a cloud > infrastructure solution. This guide shows OpenStack end users how to > create and manage resources in an OpenStack cloud with the OpenStack > dashboard and OpenStack client commands. > > Image Guide > > This guide describes how to obtain, create, and modify virtual machine > images that are compatible with OpenStack. > > CLI Reference > > This guide documents the OpenStack command-line clients. > > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140520/ec72eecd/attachment.html> From aj at suse.com Tue May 20 07:36:30 2014 From: aj at suse.com (Andreas Jaeger) Date: Tue, 20 May 2014 09:36:30 +0200 Subject: [Openstack-docs] Target audience In-Reply-To: <CAD0KtVHqbi84aHmu+PmmZfYZJmW918ebrHiTogfRvQSq=6e7jg@mail.gmail.com> References: <537A6C5D.9090600@suse.com> <CAD0KtVHqbi84aHmu+PmmZfYZJmW918ebrHiTogfRvQSq=6e7jg@mail.gmail.com> Message-ID: <537B05FE.8060701@suse.com> On 05/20/2014 07:18 AM, Anne Gentle wrote: > Thanks for analyzing Andreas and Randy! > > I like these three simple personas below. > > Alice the admin > Alice is an administrator who is responsible for maintaining (and > securing) the OpenStack cloud installation. She has many years of > experience with Linux systems administration. > > Darren the deployer > Darren is responsible for doing the initial OpenStack deployment on the > host machines. > Emile the end-user > Emile uses the cloud to do software development inside of the virtual > machines. She uses the command-line tools because she finds it quicker > than using the dashboard. Yes, these are fine - but let's rename Alice since Alice and Bob are the two persons used in the Security Guide explaining the two different setups. > To me, Emile is a useful persona because she uses user tools and > developer tools -- and I do see a lot of blending across user/dev tools. > Andreas, the user we haven't yet started to document for is the > application devops role, the operator who would monitor applications in > the cloud. They might be super specialized for monitoring of the VMs > themselves. > > But I'm not sure whether there's a fourth persona who does planning and > setup, what do you all think? Archie the architect? So, the OPS guide would be for Archie? > We also don't have to be super pattern-based, we can just write a > section describing the audience for each guide. ;) Andreas > > On Mon, May 19, 2014 at 3:41 PM, Andreas Jaeger <aj at suse.com > <mailto:aj at suse.com>> wrote: > > We had some discussion about target audience for each guide at the > OpenStack summit and Anne filed this bug: > https://bugs.launchpad.net/openstack-manuals/+bug/1319394 . As a first > step, I've went over all guides and categorized them according to target > audience and then copied all the current abstracts together. Is the > following accurate? > > Andreas > > Overview of personas/target audience: > > Operations Guide > Cloud Administrator Guide > Configuration Reference > HA Guide > Install Guide > Security Guide > Admin User Guide > > These guides target cloud administrators who sets up an OpenStack > cloud and configures the OpenStack services. > > End User Guide > Image Guide > > These guide targets users using an OpenStack cloud. > > CLI Reference > > This guide targets both cloud administrators and users using an > OpenStack cloud. > > Not covered personas: > > Developer writing applications running in an OpenStack Cloud. > > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > Detailed information - copy of current abstract: > > Install Guide > > The OpenStack? system consists of several key projects that you > install separately but that work together depending on your cloud > needs. These projects include Compute, Identity Service, Networking, > Image Service, Block Storage, Object Storage, Telemetry, > Orchestration, and Database. You can install any of these projects > separately and configure them stand-alone or as connected > entities. This guide shows you how to install OpenStack by using > packages on openSUSE through the Open Build Service Cloud > repository. Explanations of configuration options and sample > configuration files are included. > > > Operations Guide > > This book provides information about designing and operating OpenStack > clouds. > > Cloud Administrator Guide > > OpenStack offers open source software for cloud administrators to > manage and troubleshoot an OpenStack cloud. > > Configuration Reference > > This document is for system administrators who want to look up > configuration options. It contains lists of configuration options > available with OpenStack and uses auto-generation to generate options > and the descriptions from the code for each project. It includes > sample configuration files. > > HA Guide > > No abstract given. > > Security Guide > > This book provides best practices and conceptual information about > securing an OpenStack cloud. > > Admin User Guide > > OpenStack is an open source cloud computing platform for public and > private clouds. A series of interrelated projects deliver a cloud > infrastructure solution. This guide shows OpenStack admin users how to > create and manage resources in an OpenStack cloud with the OpenStack > dashboard or OpenStack client commands. > > > End User Guide > > OpenStack is an open-source cloud computing platform for public and > private clouds. A series of interrelated projects deliver a cloud > infrastructure solution. This guide shows OpenStack end users how to > create and manage resources in an OpenStack cloud with the OpenStack > dashboard and OpenStack client commands. > > Image Guide > > This guide describes how to obtain, create, and modify virtual machine > images that are compatible with OpenStack. > > CLI Reference > > This guide documents the OpenStack command-line clients. > > -- > Andreas Jaeger aj@{suse.com <http://suse.com>,opensuse.org > <http://opensuse.org>} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > <mailto:Openstack-docs at lists.openstack.org> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Tue May 20 12:12:19 2014 From: anne at openstack.org (Anne Gentle) Date: Tue, 20 May 2014 07:12:19 -0500 Subject: [Openstack-docs] Target audience In-Reply-To: <537B05FE.8060701@suse.com> References: <537A6C5D.9090600@suse.com> <CAD0KtVHqbi84aHmu+PmmZfYZJmW918ebrHiTogfRvQSq=6e7jg@mail.gmail.com> <537B05FE.8060701@suse.com> Message-ID: <CAD0KtVHWohWkRbOZag4VWhRmvyHbnxP+d-hVr1q_DGQg=Rc2Mg@mail.gmail.com> Oh we don't have to use those names in the actual metadata in the book. I was just making sure we're using personas recognized in the rest of the community. The audience statement is more like "Who this Book is For" in the Ops Guide: http://docs.openstack.org/trunk/openstack-ops/content/openstack-ops_preface.html#who-this-book-is-for On Tue, May 20, 2014 at 2:36 AM, Andreas Jaeger <aj at suse.com> wrote: > On 05/20/2014 07:18 AM, Anne Gentle wrote: > > Thanks for analyzing Andreas and Randy! > > > > I like these three simple personas below. > > > > Alice the admin > > Alice is an administrator who is responsible for maintaining (and > > securing) the OpenStack cloud installation. She has many years of > > experience with Linux systems administration. > > > > Darren the deployer > > Darren is responsible for doing the initial OpenStack deployment on the > > host machines. > > Emile the end-user > > Emile uses the cloud to do software development inside of the virtual > > machines. She uses the command-line tools because she finds it quicker > > than using the dashboard. > > Yes, these are fine - but let's rename Alice since Alice and Bob are the > two persons used in the Security Guide explaining the two different setups. > > > To me, Emile is a useful persona because she uses user tools and > > developer tools -- and I do see a lot of blending across user/dev tools. > > Andreas, the user we haven't yet started to document for is the > > application devops role, the operator who would monitor applications in > > the cloud. They might be super specialized for monitoring of the VMs > > themselves. > > > > But I'm not sure whether there's a fourth persona who does planning and > > setup, what do you all think? Archie the architect? > > So, the OPS guide would be for Archie? > > > We also don't have to be super pattern-based, we can just write a > > section describing the audience for each guide. > > ;) > > Andreas > > > > > On Mon, May 19, 2014 at 3:41 PM, Andreas Jaeger <aj at suse.com > > <mailto:aj at suse.com>> wrote: > > > > We had some discussion about target audience for each guide at the > > OpenStack summit and Anne filed this bug: > > https://bugs.launchpad.net/openstack-manuals/+bug/1319394 . As a > first > > step, I've went over all guides and categorized them according to > target > > audience and then copied all the current abstracts together. Is the > > following accurate? > > > > Andreas > > > > Overview of personas/target audience: > > > > Operations Guide > > Cloud Administrator Guide > > Configuration Reference > > HA Guide > > Install Guide > > Security Guide > > Admin User Guide > > > > These guides target cloud administrators who sets up an OpenStack > > cloud and configures the OpenStack services. > > > > End User Guide > > Image Guide > > > > These guide targets users using an OpenStack cloud. > > > > CLI Reference > > > > This guide targets both cloud administrators and users using an > > OpenStack cloud. > > > > Not covered personas: > > > > Developer writing applications running in an OpenStack Cloud. > > > > > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > Detailed information - copy of current abstract: > > > > Install Guide > > > > The OpenStack? system consists of several key projects that you > > install separately but that work together depending on your cloud > > needs. These projects include Compute, Identity Service, Networking, > > Image Service, Block Storage, Object Storage, Telemetry, > > Orchestration, and Database. You can install any of these projects > > separately and configure them stand-alone or as connected > > entities. This guide shows you how to install OpenStack by using > > packages on openSUSE through the Open Build Service Cloud > > repository. Explanations of configuration options and sample > > configuration files are included. > > > > > > Operations Guide > > > > This book provides information about designing and operating > OpenStack > > clouds. > > > > Cloud Administrator Guide > > > > OpenStack offers open source software for cloud administrators to > > manage and troubleshoot an OpenStack cloud. > > > > Configuration Reference > > > > This document is for system administrators who want to look up > > configuration options. It contains lists of configuration options > > available with OpenStack and uses auto-generation to generate options > > and the descriptions from the code for each project. It includes > > sample configuration files. > > > > HA Guide > > > > No abstract given. > > > > Security Guide > > > > This book provides best practices and conceptual information about > > securing an OpenStack cloud. > > > > Admin User Guide > > > > OpenStack is an open source cloud computing platform for public and > > private clouds. A series of interrelated projects deliver a cloud > > infrastructure solution. This guide shows OpenStack admin users how > to > > create and manage resources in an OpenStack cloud with the OpenStack > > dashboard or OpenStack client commands. > > > > > > End User Guide > > > > OpenStack is an open-source cloud computing platform for public and > > private clouds. A series of interrelated projects deliver a cloud > > infrastructure solution. This guide shows OpenStack end users how to > > create and manage resources in an OpenStack cloud with the OpenStack > > dashboard and OpenStack client commands. > > > > Image Guide > > > > This guide describes how to obtain, create, and modify virtual > machine > > images that are compatible with OpenStack. > > > > CLI Reference > > > > This guide documents the OpenStack command-line clients. > > > > -- > > Andreas Jaeger aj@{suse.com <http://suse.com>,opensuse.org > > <http://opensuse.org>} Twitter/Identica: jaegerandi > > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG > N?rnberg) > > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 > A126 > > > > _______________________________________________ > > Openstack-docs mailing list > > Openstack-docs at lists.openstack.org > > <mailto:Openstack-docs at lists.openstack.org> > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > > > > > > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140520/3a2550ed/attachment.html> From Randy_Perryman at Dell.com Tue May 20 13:15:59 2014 From: Randy_Perryman at Dell.com (Randy_Perryman at Dell.com) Date: Tue, 20 May 2014 08:15:59 -0500 Subject: [Openstack-docs] Target audience In-Reply-To: <CAD0KtVHWohWkRbOZag4VWhRmvyHbnxP+d-hVr1q_DGQg=Rc2Mg@mail.gmail.com> References: <537A6C5D.9090600@suse.com> <CAD0KtVHqbi84aHmu+PmmZfYZJmW918ebrHiTogfRvQSq=6e7jg@mail.gmail.com> <537B05FE.8060701@suse.com> <CAD0KtVHWohWkRbOZag4VWhRmvyHbnxP+d-hVr1q_DGQg=Rc2Mg@mail.gmail.com> Message-ID: <FC6A4A6096337446A48E483EA34F20502714236975@AUSX7MCPC102.AMER.DELL.COM> I like the persona and their needs. One item I like especially is Alice has an experience level ?many year of experience with Linux system administration?; do we need that for the others? Darren the deployer is experience with deployment of different Application and OS systems and responsible for deployment and documentation of the OpenStack Cluster prior to release to Alice. Emile the user has years of experience with using Linux based tool sets and is comfortable using both GUI and CLI based tools. I may be a little too picky here. ? -Randy From: Anne Gentle [mailto:anne at openstack.org] Sent: Tuesday, May 20, 2014 8:12 AM To: Andreas Jaeger Cc: openstack-docs at lists.openstack.org Subject: Re: [Openstack-docs] Target audience Oh we don't have to use those names in the actual metadata in the book. I was just making sure we're using personas recognized in the rest of the community. The audience statement is more like "Who this Book is For" in the Ops Guide: http://docs.openstack.org/trunk/openstack-ops/content/openstack-ops_preface.html#who-this-book-is-for On Tue, May 20, 2014 at 2:36 AM, Andreas Jaeger <aj at suse.com<mailto:aj at suse.com>> wrote: On 05/20/2014 07:18 AM, Anne Gentle wrote: > Thanks for analyzing Andreas and Randy! > > I like these three simple personas below. > > Alice the admin > Alice is an administrator who is responsible for maintaining (and > securing) the OpenStack cloud installation. She has many years of > experience with Linux systems administration. > > Darren the deployer > Darren is responsible for doing the initial OpenStack deployment on the > host machines. > Emile the end-user > Emile uses the cloud to do software development inside of the virtual > machines. She uses the command-line tools because she finds it quicker > than using the dashboard. Yes, these are fine - but let's rename Alice since Alice and Bob are the two persons used in the Security Guide explaining the two different setups. > To me, Emile is a useful persona because she uses user tools and > developer tools -- and I do see a lot of blending across user/dev tools. > Andreas, the user we haven't yet started to document for is the > application devops role, the operator who would monitor applications in > the cloud. They might be super specialized for monitoring of the VMs > themselves. > > But I'm not sure whether there's a fourth persona who does planning and > setup, what do you all think? Archie the architect? So, the OPS guide would be for Archie? > We also don't have to be super pattern-based, we can just write a > section describing the audience for each guide. ;) Andreas > > On Mon, May 19, 2014 at 3:41 PM, Andreas Jaeger <aj at suse.com<mailto:aj at suse.com> > <mailto:aj at suse.com<mailto:aj at suse.com>>> wrote: > > We had some discussion about target audience for each guide at the > OpenStack summit and Anne filed this bug: > https://bugs.launchpad.net/openstack-manuals/+bug/1319394 . As a first > step, I've went over all guides and categorized them according to target > audience and then copied all the current abstracts together. Is the > following accurate? > > Andreas > > Overview of personas/target audience: > > Operations Guide > Cloud Administrator Guide > Configuration Reference > HA Guide > Install Guide > Security Guide > Admin User Guide > > These guides target cloud administrators who sets up an OpenStack > cloud and configures the OpenStack services. > > End User Guide > Image Guide > > These guide targets users using an OpenStack cloud. > > CLI Reference > > This guide targets both cloud administrators and users using an > OpenStack cloud. > > Not covered personas: > > Developer writing applications running in an OpenStack Cloud. > > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > Detailed information - copy of current abstract: > > Install Guide > > The OpenStack? system consists of several key projects that you > install separately but that work together depending on your cloud > needs. These projects include Compute, Identity Service, Networking, > Image Service, Block Storage, Object Storage, Telemetry, > Orchestration, and Database. You can install any of these projects > separately and configure them stand-alone or as connected > entities. This guide shows you how to install OpenStack by using > packages on openSUSE through the Open Build Service Cloud > repository. Explanations of configuration options and sample > configuration files are included. > > > Operations Guide > > This book provides information about designing and operating OpenStack > clouds. > > Cloud Administrator Guide > > OpenStack offers open source software for cloud administrators to > manage and troubleshoot an OpenStack cloud. > > Configuration Reference > > This document is for system administrators who want to look up > configuration options. It contains lists of configuration options > available with OpenStack and uses auto-generation to generate options > and the descriptions from the code for each project. It includes > sample configuration files. > > HA Guide > > No abstract given. > > Security Guide > > This book provides best practices and conceptual information about > securing an OpenStack cloud. > > Admin User Guide > > OpenStack is an open source cloud computing platform for public and > private clouds. A series of interrelated projects deliver a cloud > infrastructure solution. This guide shows OpenStack admin users how to > create and manage resources in an OpenStack cloud with the OpenStack > dashboard or OpenStack client commands. > > > End User Guide > > OpenStack is an open-source cloud computing platform for public and > private clouds. A series of interrelated projects deliver a cloud > infrastructure solution. This guide shows OpenStack end users how to > create and manage resources in an OpenStack cloud with the OpenStack > dashboard and OpenStack client commands. > > Image Guide > > This guide describes how to obtain, create, and modify virtual machine > images that are compatible with OpenStack. > > CLI Reference > > This guide documents the OpenStack command-line clients. > > -- > Andreas Jaeger aj@{suse.com<http://suse.com> <http://suse.com>,opensuse.org<http://opensuse.org> > <http://opensuse.org>} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> > <mailto:Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org>> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -- Andreas Jaeger aj@{suse.com<http://suse.com>,opensuse.org<http://opensuse.org>} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140520/55c3a07f/attachment-0001.html> From doug.hellmann at dreamhost.com Tue May 20 14:31:17 2014 From: doug.hellmann at dreamhost.com (Doug Hellmann) Date: Tue, 20 May 2014 10:31:17 -0400 Subject: [Openstack-docs] [Heat][Documentation] Heat template documentation In-Reply-To: <37903930f5456fa6f09066fe41cce960@objectif-libre.com> References: <90d4482bcd0b7a52c7262631ffd3baef@objectif-libre.com> <CAD0KtVF6qnO4-Kd7ELxJZU53r7jtTSv7mCJG3ZVyJu-C+LxtYA@mail.gmail.com> <37903930f5456fa6f09066fe41cce960@objectif-libre.com> Message-ID: <CADb+p3RJ=cO0BxRsp7p=QiScS72dg5+ruz4WFZS9ZqyjE3sYcA@mail.gmail.com> On Fri, May 16, 2014 at 2:10 PM, Gauvain Pocentek <gauvain.pocentek at objectif-libre.com> wrote: > Le 2014-05-16 17:13, Anne Gentle a ?crit : > >> On Thu, May 15, 2014 at 10:34 AM, Gauvain Pocentek >> <gauvain.pocentek at objectif-libre.com> wrote: >> >>> Hello, >>> >>> This mail probably mainly concerns the doc team, but I guess that the >>> heat team wants to know what's going on. >>> >>> We've shortly discussed the state of heat documentation with Anne Gentle >>> and Andreas Jaeger yesterday, and I'd like to share what we think would be >>> nice to do. >>> >>> Currently we only have a small section in the user guide that describes >>> how to start a stack, but nothing documenting how to write templates. The >>> heat developer doc provides a good reference, but I think it's not easy to >>> use to get started. >>> >>> So the idea is to add an "OpenStack Orchestration" chapter in the user >>> guide that would document how to use a cloud with heat, and how to write >>> templates. >>> >>> I've drafted a spec to keep track of this at [0]. >> >> >> I'd like to experiment a bit with converting the End User Guide to an >> easier markup to enable more contributors to it. Perhaps bringing in >> Orchestration is a good point to do this, plus it may help address the >> auto-generation Steve mentions. >> >> The loss would be the single sourcing of the End User Guide and Admin >> User Guide as well as loss of PDF output and loss of translation. If >> these losses are worthwhile for easier maintenance and to encourage >> contributions from more cloud consumers, then I'd like to try an >> experiment with it. > > > Using RST would probably make it easier to import/include the developers' > documentation. But I'm not sure we can afford to loose the features you > mention. Translations for the user guides are very important I think. Sphinx does appear to have translation support: http://sphinx-doc.org/intl.html?highlight=translation I've never used the feature myself, so I don't know how good the workflow is. Sphinx will generate PDFs, though the LaTeX output is not as nice looking as what we get now. There's also a direct-to-pdf builder that uses rst2pdf that appears to support templates, so that might be an easier path to producing something attractive: http://ralsina.me/static/manual.pdf > > How would we review changes made in "external" repositories? The user guides > are continuously published, this means that a change done in the heat/docs/ > dir would quite quickly land on the webserver without a doc team review. I > completely trust the developers, but I'm not sure that this is the way to > go. > > >> >> The experiment would be to have a new repo set up, >> openstack/user-guide and use the docs-core team as reviewers on it. >> Convert the End User Guide from DocBook to RST and build with Sphinx. >> Use the oslosphinx tempate for output. But what I don't know is if >> it's possible to build the automated output outside of the >> openstack/heat repo, does anyone have interest in doing a proof of >> concept on this? > > > I'm not sure that this is possible, but I'm no RST expert. I'm not sure this quite answers the question, but the RST directives for auto-generating docs from code usually depend on being able to import the code. That means heat and its dependencies would need to be installed on the system where the build is performed. We accomplish this in the dev doc builds by using tox, which automatically handles the installation as part of setting up the virtualenv where the build command runs. > > >> I'd also like input on the loss of features I'm describing above. Is >> this worth experimenting with? > > > Starting this new book sounds like a lot of work. Right now I'm not > convinced it's worth it. > > Gauvain > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs From anne at openstack.org Tue May 20 22:03:46 2014 From: anne at openstack.org (Anne Gentle) Date: Tue, 20 May 2014 17:03:46 -0500 Subject: [Openstack-docs] Armed with roadmaps and bug lists, amazing docs happen Message-ID: <CAD0KtVFJJE5FruGORFrZwv6UMAxCguUDiOScShzfXiJcMYy3mw@mail.gmail.com> Hi all, I've proposed roadmaps to live in-repo for each book in the openstack-manuals repository: https://review.openstack.org/94387 https://review.openstack.org/94389 https://review.openstack.org/94386 https://review.openstack.org/94388 https://review.openstack.org/94384 https://review.openstack.org/94390 https://review.openstack.org/94385 I'd like input on the process we can implement for these roadmaps. I'd like bugs to be reserved for actual defects and blueprints to be reserved for large coordinated efforts. Roadmap tasks are additional information that enhances the particular guide targeted with the roadmap. A roadmap should give walk-up contributors a list of things they could do if they're so inclined. How can a contributor indicate they're working on a roadmap task so we avoid duplication of effort? Submit a work-in-progress patch is all I have proposed so far. Is that work-able? Let me know your thoughts on how to make a roadmap work (and don't make me set up a docs-specs repo please). :) Thanks, Anne -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140520/84673c63/attachment.html> From mkassawara at gmail.com Wed May 21 01:05:11 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Tue, 20 May 2014 19:05:11 -0600 Subject: [Openstack-docs] Armed with roadmaps and bug lists, amazing docs happen In-Reply-To: <CAD0KtVFJJE5FruGORFrZwv6UMAxCguUDiOScShzfXiJcMYy3mw@mail.gmail.com> References: <CAD0KtVFJJE5FruGORFrZwv6UMAxCguUDiOScShzfXiJcMYy3mw@mail.gmail.com> Message-ID: <CABA+jQonoYncJCfAQE2TtHk6PMPz+FcrOyoAG9TqzTV48sVzhg@mail.gmail.com> We definitely need one place (or one type of place) to find the task list for each book/document and indicate ownership for particular tasks. I like the more formal nature of including a file in each repo that requires agreement through the review process to change roadmap components. However, assigning a task to myself also requires the review process and I'm not sure we need that complexity for this particular type of change. A wiki helps the latter situation, but lacks control and history of the roadmap components. Maybe we can self-approve task assignments? On Tue, May 20, 2014 at 4:03 PM, Anne Gentle <anne at openstack.org> wrote: > Hi all, > I've proposed roadmaps to live in-repo for each book in the > openstack-manuals repository: > > https://review.openstack.org/94387 > https://review.openstack.org/94389 > https://review.openstack.org/94386 > https://review.openstack.org/94388 > https://review.openstack.org/94384 > https://review.openstack.org/94390 > https://review.openstack.org/94385 > > I'd like input on the process we can implement for these roadmaps. I'd > like bugs to be reserved for actual defects and blueprints to be reserved > for large coordinated efforts. > > Roadmap tasks are additional information that enhances the particular > guide targeted with the roadmap. A roadmap should give walk-up contributors > a list of things they could do if they're so inclined. How can a > contributor indicate they're working on a roadmap task so we avoid > duplication of effort? Submit a work-in-progress patch is all I have > proposed so far. Is that work-able? Let me know your thoughts on how to > make a roadmap work (and don't make me set up a docs-specs repo please). :) > > Thanks, > Anne > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140520/93d8d286/attachment.html> From mkassawara at gmail.com Wed May 21 01:32:57 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Tue, 20 May 2014 19:32:57 -0600 Subject: [Openstack-docs] Improvements to the Installation Guide In-Reply-To: <CABA+jQpeS+Osy3aKdUG=pTuZN6V-v0Wh52GA52AKX=ycVsMnrQ@mail.gmail.com> References: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> <53788287.4020203@b1-systems.de> <CABA+jQo1HwmujP_BL4W7AkdUs=5Zr6xDSUGD_z477UXqrxXdWw@mail.gmail.com> <CAD0KtVE+BEpom3DSwE_h-0XtCq3UwgUhbE8bgo9y731g0mQL_Q@mail.gmail.com> <CABA+jQpeS+Osy3aKdUG=pTuZN6V-v0Wh52GA52AKX=ycVsMnrQ@mail.gmail.com> Message-ID: <CABA+jQrMcV_9Ro99G_Ou5Up0jTgFBibNpvFAqgUNDYP+ExO+oQ@mail.gmail.com> Anne, I finished the etherpad-to-wiki conversion. Matt On Sun, May 18, 2014 at 5:02 PM, Matt Kassawara <mkassawara at gmail.com>wrote: > Any centralized place that we can agree upon to track activity works for > me... wiki, etherpad, bug, etc. This also applies to roadmaps. I almost > wish we could extend blueprints to handle roadmaps... essentially "living" > blueprints that remain open and flexible for the duration of a project. > > > On Sun, May 18, 2014 at 3:15 PM, Anne Gentle <anne at openstack.org> wrote: > >> >> >> >> On Sun, May 18, 2014 at 8:00 AM, Matt Kassawara <mkassawara at gmail.com>wrote: >> >>> I suppose we can use the "work items" section in the blueprint or note >>> activities on the Wiki page. >>> >> >> If you're all willing to work this way, I think it helps us know the >> "quality" of our docs set by tracking bugs as defect or inaccuracy rather >> than reorg or gap-filling. What do you think? Is it work-able to track on >> the wiki page? >> >> Let's also talk about how we can make a roadmap-per-book workable while >> still not causing duplication of effort. My original thinking is that you'd >> update the roadmap with your patch, but now I realize 2 people could work >> on a roadmap item at once without knowing the other is doing the same >> thing. Thoughts? >> Thanks, >> Anne >> >> >>> >>> On Sun, May 18, 2014 at 3:51 AM, Christian Berendt < >>> berendt at b1-systems.de> wrote: >>> >>>> On 05/18/2014 03:32 AM, Matt Kassawara wrote: >>>> > The suggested changes currently live in an Etherpad. >>>> > >>>> > https://etherpad.openstack.org/p/installation-guide-audit >>>> >>>> Will there be bugs opened first for all the changes mentioned in the >>>> Etherpad? I would like to take over some changes but I'm not sure who is >>>> responsible for the several changes at the moment and if there is >>>> somebody already assigned. >>>> >>>> Christian. >>>> >>>> -- >>>> Christian Berendt >>>> Cloud Computing Solution Architect >>>> Mail: berendt at b1-systems.de >>>> >>>> B1 Systems GmbH >>>> Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de >>>> GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 >>>> >>>> _______________________________________________ >>>> Openstack-docs mailing list >>>> Openstack-docs at lists.openstack.org >>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>>> >>> >>> >>> _______________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.openstack.org >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>> >>> >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140520/d9693f77/attachment.html> From openstack at lanabrindley.com Wed May 21 03:14:51 2014 From: openstack at lanabrindley.com (Lana Brindley) Date: Wed, 21 May 2014 13:14:51 +1000 Subject: [Openstack-docs] Armed with roadmaps and bug lists, amazing docs happen In-Reply-To: <CABA+jQonoYncJCfAQE2TtHk6PMPz+FcrOyoAG9TqzTV48sVzhg@mail.gmail.com> References: <CAD0KtVFJJE5FruGORFrZwv6UMAxCguUDiOScShzfXiJcMYy3mw@mail.gmail.com> <CABA+jQonoYncJCfAQE2TtHk6PMPz+FcrOyoAG9TqzTV48sVzhg@mail.gmail.com> Message-ID: <537C1A2B.9020105@lanabrindley.com> Yeah, I'm with Matt on this one. It doesn't really bother me where the list is stored, as long as it's easy to find, easy to update, and easy to use. Having to go through an approval/review process to assign work to yourself will just mean that people get bored and wander off in between deciding to do something, and waiting for the approval to do it. L On 21/05/14 11:05, Matt Kassawara wrote: > We definitely need one place (or one type of place) to find the task > list for each book/document and indicate ownership for particular tasks. > I like the more formal nature of including a file in each repo that > requires agreement through the review process to change roadmap > components. However, assigning a task to myself also requires the review > process and I'm not sure we need that complexity for this particular > type of change. A wiki helps the latter situation, but lacks control and > history of the roadmap components. Maybe we can self-approve task > assignments? > > > On Tue, May 20, 2014 at 4:03 PM, Anne Gentle <anne at openstack.org > <mailto:anne at openstack.org>> wrote: > > Hi all, > I've proposed roadmaps to live in-repo for each book in the > openstack-manuals repository: > > https://review.openstack.org/94387 > https://review.openstack.org/94389 > https://review.openstack.org/94386 > https://review.openstack.org/94388 > https://review.openstack.org/94384 > https://review.openstack.org/94390 > https://review.openstack.org/94385 > > I'd like input on the process we can implement for these roadmaps. > I'd like bugs to be reserved for actual defects and blueprints to be > reserved for large coordinated efforts. > > Roadmap tasks are additional information that enhances the > particular guide targeted with the roadmap. A roadmap should give > walk-up contributors a list of things they could do if they're so > inclined. How can a contributor indicate they're working on a > roadmap task so we avoid duplication of effort? Submit a > work-in-progress patch is all I have proposed so far. Is that > work-able? Let me know your thoughts on how to make a roadmap work > (and don't make me set up a docs-specs repo please). :) > > Thanks, > Anne > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > <mailto:Openstack-docs at lists.openstack.org> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -- Lana Brindley Technical Writer Rackspace Cloud Builders Australia http://lanabrindley.com From berendt at b1-systems.de Wed May 21 05:42:40 2014 From: berendt at b1-systems.de (Christian Berendt) Date: Wed, 21 May 2014 07:42:40 +0200 Subject: [Openstack-docs] Improvements to the Installation Guide In-Reply-To: <CABA+jQrMcV_9Ro99G_Ou5Up0jTgFBibNpvFAqgUNDYP+ExO+oQ@mail.gmail.com> References: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> <53788287.4020203@b1-systems.de> <CABA+jQo1HwmujP_BL4W7AkdUs=5Zr6xDSUGD_z477UXqrxXdWw@mail.gmail.com> <CAD0KtVE+BEpom3DSwE_h-0XtCq3UwgUhbE8bgo9y731g0mQL_Q@mail.gmail.com> <CABA+jQpeS+Osy3aKdUG=pTuZN6V-v0Wh52GA52AKX=ycVsMnrQ@mail.gmail.com> <CABA+jQrMcV_9Ro99G_Ou5Up0jTgFBibNpvFAqgUNDYP+ExO+oQ@mail.gmail.com> Message-ID: <537C3CD0.1000508@b1-systems.de> On 05/21/2014 03:32 AM, Matt Kassawara wrote: > I finished the etherpad-to-wiki conversion. Could you please post the URL? Don't find it right now. Thanks, Christian. -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 From lisa.m.marino at hp.com Wed May 21 09:37:05 2014 From: lisa.m.marino at hp.com (Marino, Lisa Michele) Date: Wed, 21 May 2014 09:37:05 +0000 Subject: [Openstack-docs] new contributor needs git-review setup assistance Message-ID: <65E82A781FA20A4D81EF9EA3F17C8E737812E9@G1W3641.americas.hpqcorp.net> HI there, I have just joined as a contributor and was following the repo setup instructions here: https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers I got hung up on the install git-review step, specifically "python setup.py install" command. Is there anyone who can help me with this? Thanks! Lsisa Lisa Michele Marino Information Developer HP Helion lisa.m.marino at hp.com T 001 + 412-307-4992 M 001 + 919-931-3165 Hewlett-Packard Company 5097 W Harbison Rd Pittsburgh PA 15205 USA [cid:image001.png at 01CF6887.B1D47C00] -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/171bee59/attachment.html> -------------- next part -------------- A non-text attachment was scrubbed... Name: image001.png Type: image/png Size: 3850 bytes Desc: image001.png URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/171bee59/attachment.png> From berendt at b1-systems.de Wed May 21 12:06:54 2014 From: berendt at b1-systems.de (Christian Berendt) Date: Wed, 21 May 2014 14:06:54 +0200 Subject: [Openstack-docs] new contributor needs git-review setup assistance In-Reply-To: <65E82A781FA20A4D81EF9EA3F17C8E737812E9@G1W3641.americas.hpqcorp.net> References: <65E82A781FA20A4D81EF9EA3F17C8E737812E9@G1W3641.americas.hpqcorp.net> Message-ID: <537C96DE.8020208@b1-systems.de> On 05/21/2014 11:37 AM, Marino, Lisa Michele wrote: > I got hung up on the install git-review step, specifically ?python > setup.py install? command. Is there anyone who can help me with this? Just check if your distribution already provides git-review as a distribution package (e.g. yum search git-review or zypper search git-review). Or use pip to install git-review (pip install git-review). HTH, Christian. -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 From mkassawara at gmail.com Wed May 21 12:49:10 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Wed, 21 May 2014 06:49:10 -0600 Subject: [Openstack-docs] Improvements to the Installation Guide In-Reply-To: <537C3CD0.1000508@b1-systems.de> References: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> <53788287.4020203@b1-systems.de> <CABA+jQo1HwmujP_BL4W7AkdUs=5Zr6xDSUGD_z477UXqrxXdWw@mail.gmail.com> <CAD0KtVE+BEpom3DSwE_h-0XtCq3UwgUhbE8bgo9y731g0mQL_Q@mail.gmail.com> <CABA+jQpeS+Osy3aKdUG=pTuZN6V-v0Wh52GA52AKX=ycVsMnrQ@mail.gmail.com> <CABA+jQrMcV_9Ro99G_Ou5Up0jTgFBibNpvFAqgUNDYP+ExO+oQ@mail.gmail.com> <537C3CD0.1000508@b1-systems.de> Message-ID: <CABA+jQrV0AH4HMG4Vd5piPAAOY_LDb5Gbirtv0Q=MAKe8pALWg@mail.gmail.com> https://wiki.openstack.org/wiki/Documentation/InstallationGuideImprovements You can also find it in the blueprint specs. On Tue, May 20, 2014 at 11:42 PM, Christian Berendt <berendt at b1-systems.de>wrote: > On 05/21/2014 03:32 AM, Matt Kassawara wrote: > > I finished the etherpad-to-wiki conversion. > > Could you please post the URL? Don't find it right now. > > Thanks, Christian. > > -- > Christian Berendt > Cloud Computing Solution Architect > Mail: berendt at b1-systems.de > > B1 Systems GmbH > Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de > GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/17075efe/attachment.html> From berendt at b1-systems.de Wed May 21 13:41:18 2014 From: berendt at b1-systems.de (Christian Berendt) Date: Wed, 21 May 2014 15:41:18 +0200 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook Message-ID: <537CACFE.7090604@b1-systems.de> Even I like AsciiDoc I would suggest to convert the HA guide from AsciiDoc to DocBook. All other guides are written in DocBox and I don't see any benefit of keeping the HA guide in AsciiDoc. Christian. -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 From aj at suse.com Wed May 21 13:47:22 2014 From: aj at suse.com (Andreas Jaeger) Date: Wed, 21 May 2014 15:47:22 +0200 Subject: [Openstack-docs] Armed with roadmaps and bug lists, amazing docs happen In-Reply-To: <537C1A2B.9020105@lanabrindley.com> References: <CAD0KtVFJJE5FruGORFrZwv6UMAxCguUDiOScShzfXiJcMYy3mw@mail.gmail.com> <CABA+jQonoYncJCfAQE2TtHk6PMPz+FcrOyoAG9TqzTV48sVzhg@mail.gmail.com> <537C1A2B.9020105@lanabrindley.com> Message-ID: <537CAE6A.4040206@suse.com> On 05/21/2014 05:14 AM, Lana Brindley wrote: > Yeah, I'm with Matt on this one. It doesn't really bother me where the > list is stored, as long as it's easy to find, easy to update, and easy > to use. Having to go through an approval/review process to assign work > to yourself will just mean that people get bored and wander off in > between deciding to do something, and waiting for the approval to do it. And if a non-core wants to do something, one of us cores can quickly approve it... This should be a lightweight process, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Wed May 21 13:48:22 2014 From: anne at openstack.org (Anne Gentle) Date: Wed, 21 May 2014 08:48:22 -0500 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <537CACFE.7090604@b1-systems.de> References: <537CACFE.7090604@b1-systems.de> Message-ID: <CAD0KtVErmigCF2=uUW5_X49ouTx7su455yGY0hCkAuTXXBdMZQ@mail.gmail.com> Glad you brought it up again. Last time someone asked a year ago, here's how it went: http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.html Seems like a recurring theme. Let's see what happens this time around. Anne On Wed, May 21, 2014 at 8:41 AM, Christian Berendt <berendt at b1-systems.de>wrote: > Even I like AsciiDoc I would suggest to convert the HA guide from > AsciiDoc to DocBook. All other guides are written in DocBox and I don't > see any benefit of keeping the HA guide in AsciiDoc. > > Christian. > > -- > Christian Berendt > Cloud Computing Solution Architect > Mail: berendt at b1-systems.de > > B1 Systems GmbH > Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de > GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/9a78093c/attachment.html> From diane.fleming at RACKSPACE.COM Wed May 21 13:52:16 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Wed, 21 May 2014 13:52:16 +0000 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CAD0KtVErmigCF2=uUW5_X49ouTx7su455yGY0hCkAuTXXBdMZQ@mail.gmail.com> Message-ID: <CFA219AD.2D984%diane.fleming@rackspace.com> Yes please! I'm happy to convert it if everyone agrees. Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com From: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>> Date: Wednesday, May 21, 2014 8:48 AM To: Christian Berendt <berendt at b1-systems.de<mailto:berendt at b1-systems.de>> Cc: "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org>> Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook Glad you brought it up again. Last time someone asked a year ago, here's how it went: http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.html Seems like a recurring theme. Let's see what happens this time around. Anne On Wed, May 21, 2014 at 8:41 AM, Christian Berendt <berendt at b1-systems.de<mailto:berendt at b1-systems.de>> wrote: Even I like AsciiDoc I would suggest to convert the HA guide from AsciiDoc to DocBook. All other guides are written in DocBox and I don't see any benefit of keeping the HA guide in AsciiDoc. Christian. -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de<mailto:berendt at b1-systems.de> B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/46ab195c/attachment.html> From aj at suse.com Wed May 21 14:00:14 2014 From: aj at suse.com (Andreas Jaeger) Date: Wed, 21 May 2014 16:00:14 +0200 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CFA219AD.2D984%diane.fleming@rackspace.com> References: <CFA219AD.2D984%diane.fleming@rackspace.com> Message-ID: <537CB16E.5090809@suse.com> On 05/21/2014 03:52 PM, Diane Fleming wrote: > Yes please! I'm happy to convert it if everyone agrees. After working on these two patches: https://review.openstack.org/#/c/94318/ https://review.openstack.org/#/c/94319/ that workaround bugs in our asciitools conversion, I'm more than willing to go to it, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From berendt at b1-systems.de Wed May 21 14:02:02 2014 From: berendt at b1-systems.de (Christian Berendt) Date: Wed, 21 May 2014 16:02:02 +0200 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <537CB16E.5090809@suse.com> References: <CFA219AD.2D984%diane.fleming@rackspace.com> <537CB16E.5090809@suse.com> Message-ID: <537CB1DA.6000306@b1-systems.de> On 05/21/2014 04:00 PM, Andreas Jaeger wrote: > that workaround bugs in our asciitools conversion, I'm more than willing > to go to it, That's why I started this thread. I think we should not start to pollute/complicate the doc or build tools with specific workarounds for AsciiDoc when there only exists one guide using AsciiDoc. Christian. -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 From nchase at mirantis.com Wed May 21 14:22:50 2014 From: nchase at mirantis.com (Nick Chase) Date: Wed, 21 May 2014 10:22:50 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CFA219AD.2D984%diane.fleming@rackspace.com> References: <CAD0KtVErmigCF2=uUW5_X49ouTx7su455yGY0hCkAuTXXBdMZQ@mail.gmail.com> <CFA219AD.2D984%diane.fleming@rackspace.com> Message-ID: <CA+p99Gno4qkhpAVO_WrUWiiu7e-wm6qXo9yhyegzd8OjvTjn9w@mail.gmail.com> I'd be happy to do the conversion; it's something I'm familiar with, I have blocks of time where I can do it, and Diane, you can be more useful doing stuff that I can't, as a rule. That said, if you're set on doing it yourself, I won't stop you. :) Let me know. ---- Nick On Wed, May 21, 2014 at 9:52 AM, Diane Fleming <diane.fleming at rackspace.com>wrote: > Yes please! I'm happy to convert it if everyone agrees. > > > *Diane* > *----------------------------------------------* > Diane Fleming > Software Developer II - US > diane.fleming at rackspace.com > Cell 512.323.6799 > Office 512.874.1260 > Skype drfleming0227 > Google-plus diane.fleming at gmail.com > > From: Anne Gentle <anne at openstack.org> > Date: Wednesday, May 21, 2014 8:48 AM > To: Christian Berendt <berendt at b1-systems.de> > Cc: "openstack-docs at lists.openstack.org" < > Openstack-docs at lists.openstack.org> > Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to > DocBook > > Glad you brought it up again. Last time someone asked a year ago, > here's how it went: > > http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.html > > Seems like a recurring theme. Let's see what happens this time around. > > Anne > > > On Wed, May 21, 2014 at 8:41 AM, Christian Berendt <berendt at b1-systems.de>wrote: > >> Even I like AsciiDoc I would suggest to convert the HA guide from >> AsciiDoc to DocBook. All other guides are written in DocBox and I don't >> see any benefit of keeping the HA guide in AsciiDoc. >> >> Christian. >> >> -- >> Christian Berendt >> Cloud Computing Solution Architect >> Mail: berendt at b1-systems.de >> >> B1 Systems GmbH >> Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de >> GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/7711c05a/attachment.html> From sgordon at redhat.com Wed May 21 14:37:02 2014 From: sgordon at redhat.com (Steve Gordon) Date: Wed, 21 May 2014 10:37:02 -0400 (EDT) Subject: [Openstack-docs] Armed with roadmaps and bug lists, amazing docs happen In-Reply-To: <CABA+jQonoYncJCfAQE2TtHk6PMPz+FcrOyoAG9TqzTV48sVzhg@mail.gmail.com> References: <CAD0KtVFJJE5FruGORFrZwv6UMAxCguUDiOScShzfXiJcMYy3mw@mail.gmail.com> <CABA+jQonoYncJCfAQE2TtHk6PMPz+FcrOyoAG9TqzTV48sVzhg@mail.gmail.com> Message-ID: <594042561.15420012.1400683022696.JavaMail.zimbra@redhat.com> ----- Original Message ----- > From: "Matt Kassawara" <mkassawara at gmail.com> > To: "Anne Gentle" <anne at openstack.org> > Cc: openstack-docs at lists.openstack.org > Sent: Tuesday, May 20, 2014 9:05:11 PM > Subject: Re: [Openstack-docs] Armed with roadmaps and bug lists, amazing docs happen > > We definitely need one place (or one type of place) to find the task list > for each book/document and indicate ownership for particular tasks. I like > the more formal nature of including a file in each repo that requires > agreement through the review process to change roadmap components. However, > assigning a task to myself also requires the review process and I'm not > sure we need that complexity for this particular type of change. A wiki > helps the latter situation, but lacks control and history of the roadmap > components. Maybe we can self-approve task assignments? What about having a blueprint per book and using the link a bug report feature to break out tasks? -Steve From diane.fleming at RACKSPACE.COM Wed May 21 15:21:52 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Wed, 21 May 2014 15:21:52 +0000 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CA+p99Gno4qkhpAVO_WrUWiiu7e-wm6qXo9yhyegzd8OjvTjn9w@mail.gmail.com> Message-ID: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> Sure Nick, have at it! Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com From: Nick Chase <nchase at mirantis.com<mailto:nchase at mirantis.com>> Date: Wednesday, May 21, 2014 9:22 AM To: Diane Fleming <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>> Cc: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>>, Christian Berendt <berendt at b1-systems.de<mailto:berendt at b1-systems.de>>, "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org>> Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook I'd be happy to do the conversion; it's something I'm familiar with, I have blocks of time where I can do it, and Diane, you can be more useful doing stuff that I can't, as a rule. That said, if you're set on doing it yourself, I won't stop you. :) Let me know. ---- Nick On Wed, May 21, 2014 at 9:52 AM, Diane Fleming <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>> wrote: Yes please! I'm happy to convert it if everyone agrees. Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com> Cell 512.323.6799<tel:512.323.6799> Office 512.874.1260<tel:512.874.1260> Skype drfleming0227 Google-plus diane.fleming at gmail.com<mailto:diane.fleming at gmail.com> From: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>> Date: Wednesday, May 21, 2014 8:48 AM To: Christian Berendt <berendt at b1-systems.de<mailto:berendt at b1-systems.de>> Cc: "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org>> Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook Glad you brought it up again. Last time someone asked a year ago, here's how it went: http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.html Seems like a recurring theme. Let's see what happens this time around. Anne On Wed, May 21, 2014 at 8:41 AM, Christian Berendt <berendt at b1-systems.de<mailto:berendt at b1-systems.de>> wrote: Even I like AsciiDoc I would suggest to convert the HA guide from AsciiDoc to DocBook. All other guides are written in DocBox and I don't see any benefit of keeping the HA guide in AsciiDoc. Christian. -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de<mailto:berendt at b1-systems.de> B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/f4b0f4d2/attachment.html> From nchase at mirantis.com Wed May 21 15:41:39 2014 From: nchase at mirantis.com (Nicholas Chase) Date: Wed, 21 May 2014 11:41:39 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> Message-ID: <537CC933.6070106@mirantis.com> Will do! Give me a couple of days and it'll be in and ready for review. ---- Nick On 5/21/2014 11:21 AM, Diane Fleming wrote: > Sure Nick, have at it! > > /Diane/ > /----------------------------------------------/ > Diane Fleming > Software Developer II - US > diane.fleming at rackspace.com > Cell 512.323.6799 > Office 512.874.1260 > Skype drfleming0227 > Google-plus diane.fleming at gmail.com > > From: Nick Chase <nchase at mirantis.com <mailto:nchase at mirantis.com>> > Date: Wednesday, May 21, 2014 9:22 AM > To: Diane Fleming <diane.fleming at rackspace.com > <mailto:diane.fleming at rackspace.com>> > Cc: Anne Gentle <anne at openstack.org <mailto:anne at openstack.org>>, > Christian Berendt <berendt at b1-systems.de > <mailto:berendt at b1-systems.de>>, "openstack-docs at lists.openstack.org > <mailto:openstack-docs at lists.openstack.org>" > <Openstack-docs at lists.openstack.org > <mailto:Openstack-docs at lists.openstack.org>> > Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook > > I'd be happy to do the conversion; it's something I'm familiar with, I > have blocks of time where I can do it, and Diane, you can be more useful > doing stuff that I can't, as a rule. > > That said, if you're set on doing it yourself, I won't stop you. :) > > Let me know. > > ---- Nick > > > On Wed, May 21, 2014 at 9:52 AM, Diane Fleming > <diane.fleming at rackspace.com <mailto:diane.fleming at rackspace.com>> wrote: > > Yes please! I'm happy to convert it if everyone agrees. > > > /Diane/ > /----------------------------------------------/ > Diane Fleming > Software Developer II - US > diane.fleming at rackspace.com <mailto:diane.fleming at rackspace.com> > Cell 512.323.6799 <tel:512.323.6799> > Office 512.874.1260 <tel:512.874.1260> > Skype drfleming0227 > Google-plus diane.fleming at gmail.com <mailto:diane.fleming at gmail.com> > > From: Anne Gentle <anne at openstack.org <mailto:anne at openstack.org>> > Date: Wednesday, May 21, 2014 8:48 AM > To: Christian Berendt <berendt at b1-systems.de > <mailto:berendt at b1-systems.de>> > Cc: "openstack-docs at lists.openstack.org > <mailto:openstack-docs at lists.openstack.org>" > <Openstack-docs at lists.openstack.org > <mailto:Openstack-docs at lists.openstack.org>> > Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to > DocBook > > Glad you brought it up again. Last time someone asked a year ago, > here's how it went: > > http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.html > > Seems like a recurring theme. Let's see what happens this time around. > > Anne > > > On Wed, May 21, 2014 at 8:41 AM, Christian Berendt > <berendt at b1-systems.de <mailto:berendt at b1-systems.de>> wrote: > > Even I like AsciiDoc I would suggest to convert the HA guide from > AsciiDoc to DocBook. All other guides are written in DocBox and > I don't > see any benefit of keeping the HA guide in AsciiDoc. > > Christian. > > -- > Christian Berendt > Cloud Computing Solution Architect > Mail: berendt at b1-systems.de <mailto:berendt at b1-systems.de> > > B1 Systems GmbH > Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de > GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: > Ingolstadt,HRB 3537 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > <mailto:Openstack-docs at lists.openstack.org> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > <mailto:Openstack-docs at lists.openstack.org> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > From anne at openstack.org Wed May 21 15:49:21 2014 From: anne at openstack.org (Anne Gentle) Date: Wed, 21 May 2014 10:49:21 -0500 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <537CC933.6070106@mirantis.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> Message-ID: <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> Sounds good. If anyone has objections to the conversion, please engage in the review. Thanks, Anne On Wed, May 21, 2014 at 10:41 AM, Nicholas Chase <nchase at mirantis.com>wrote: > Will do! Give me a couple of days and it'll be in and ready for review. > > ---- Nick > > > On 5/21/2014 11:21 AM, Diane Fleming wrote: > >> Sure Nick, have at it! >> >> /Diane/ >> /----------------------------------------------/ >> >> Diane Fleming >> Software Developer II - US >> diane.fleming at rackspace.com >> Cell 512.323.6799 >> Office 512.874.1260 >> Skype drfleming0227 >> Google-plus diane.fleming at gmail.com >> >> From: Nick Chase <nchase at mirantis.com <mailto:nchase at mirantis.com>> >> >> Date: Wednesday, May 21, 2014 9:22 AM >> To: Diane Fleming <diane.fleming at rackspace.com >> <mailto:diane.fleming at rackspace.com>> >> Cc: Anne Gentle <anne at openstack.org <mailto:anne at openstack.org>>, >> Christian Berendt <berendt at b1-systems.de >> <mailto:berendt at b1-systems.de>>, "openstack-docs at lists.openstack.org >> <mailto:openstack-docs at lists.openstack.org>" >> <Openstack-docs at lists.openstack.org >> <mailto:Openstack-docs at lists.openstack.org>> >> >> Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to >> DocBook >> >> I'd be happy to do the conversion; it's something I'm familiar with, I >> have blocks of time where I can do it, and Diane, you can be more useful >> doing stuff that I can't, as a rule. >> >> That said, if you're set on doing it yourself, I won't stop you. :) >> >> Let me know. >> >> ---- Nick >> >> >> On Wed, May 21, 2014 at 9:52 AM, Diane Fleming >> <diane.fleming at rackspace.com <mailto:diane.fleming at rackspace.com>> wrote: >> >> Yes please! I'm happy to convert it if everyone agrees. >> >> >> /Diane/ >> /----------------------------------------------/ >> >> Diane Fleming >> Software Developer II - US >> diane.fleming at rackspace.com <mailto:diane.fleming at rackspace.com> >> Cell 512.323.6799 <tel:512.323.6799> >> Office 512.874.1260 <tel:512.874.1260> >> Skype drfleming0227 >> Google-plus diane.fleming at gmail.com <mailto:diane.fleming at gmail.com> >> >> From: Anne Gentle <anne at openstack.org <mailto:anne at openstack.org>> >> >> Date: Wednesday, May 21, 2014 8:48 AM >> To: Christian Berendt <berendt at b1-systems.de >> <mailto:berendt at b1-systems.de>> >> Cc: "openstack-docs at lists.openstack.org >> <mailto:openstack-docs at lists.openstack.org>" >> <Openstack-docs at lists.openstack.org >> <mailto:Openstack-docs at lists.openstack.org>> >> >> Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to >> DocBook >> >> Glad you brought it up again. Last time someone asked a year ago, >> here's how it went: >> >> http://lists.openstack.org/pipermail/openstack-docs/2013- >> May/001630.html >> >> Seems like a recurring theme. Let's see what happens this time around. >> >> Anne >> >> >> On Wed, May 21, 2014 at 8:41 AM, Christian Berendt >> <berendt at b1-systems.de <mailto:berendt at b1-systems.de>> wrote: >> >> Even I like AsciiDoc I would suggest to convert the HA guide from >> AsciiDoc to DocBook. All other guides are written in DocBox and >> I don't >> see any benefit of keeping the HA guide in AsciiDoc. >> >> Christian. >> >> -- >> Christian Berendt >> Cloud Computing Solution Architect >> Mail: berendt at b1-systems.de <mailto:berendt at b1-systems.de> >> >> >> B1 Systems GmbH >> Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de >> GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: >> Ingolstadt,HRB 3537 >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> <mailto:Openstack-docs at lists.openstack.org> >> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/ >> openstack-docs >> >> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> <mailto:Openstack-docs at lists.openstack.org> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> >> -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/ace962ec/attachment.html> From mkassawara at gmail.com Wed May 21 15:58:54 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Wed, 21 May 2014 09:58:54 -0600 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> Message-ID: <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> Shall we play pin the -1 on the patch? :) On Wed, May 21, 2014 at 9:49 AM, Anne Gentle <anne at openstack.org> wrote: > Sounds good. If anyone has objections to the conversion, please engage in > the review. > Thanks, > Anne > > > On Wed, May 21, 2014 at 10:41 AM, Nicholas Chase <nchase at mirantis.com>wrote: > >> Will do! Give me a couple of days and it'll be in and ready for review. >> >> ---- Nick >> >> >> On 5/21/2014 11:21 AM, Diane Fleming wrote: >> >>> Sure Nick, have at it! >>> >>> /Diane/ >>> /----------------------------------------------/ >>> >>> Diane Fleming >>> Software Developer II - US >>> diane.fleming at rackspace.com >>> Cell 512.323.6799 >>> Office 512.874.1260 >>> Skype drfleming0227 >>> Google-plus diane.fleming at gmail.com >>> >>> From: Nick Chase <nchase at mirantis.com <mailto:nchase at mirantis.com>> >>> >>> Date: Wednesday, May 21, 2014 9:22 AM >>> To: Diane Fleming <diane.fleming at rackspace.com >>> <mailto:diane.fleming at rackspace.com>> >>> Cc: Anne Gentle <anne at openstack.org <mailto:anne at openstack.org>>, >>> Christian Berendt <berendt at b1-systems.de >>> <mailto:berendt at b1-systems.de>>, "openstack-docs at lists.openstack.org >>> <mailto:openstack-docs at lists.openstack.org>" >>> <Openstack-docs at lists.openstack.org >>> <mailto:Openstack-docs at lists.openstack.org>> >>> >>> Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to >>> DocBook >>> >>> I'd be happy to do the conversion; it's something I'm familiar with, I >>> have blocks of time where I can do it, and Diane, you can be more useful >>> doing stuff that I can't, as a rule. >>> >>> That said, if you're set on doing it yourself, I won't stop you. :) >>> >>> Let me know. >>> >>> ---- Nick >>> >>> >>> On Wed, May 21, 2014 at 9:52 AM, Diane Fleming >>> <diane.fleming at rackspace.com <mailto:diane.fleming at rackspace.com>> >>> wrote: >>> >>> Yes please! I'm happy to convert it if everyone agrees. >>> >>> >>> /Diane/ >>> /----------------------------------------------/ >>> >>> Diane Fleming >>> Software Developer II - US >>> diane.fleming at rackspace.com <mailto:diane.fleming at rackspace.com> >>> Cell 512.323.6799 <tel:512.323.6799> >>> Office 512.874.1260 <tel:512.874.1260> >>> Skype drfleming0227 >>> Google-plus diane.fleming at gmail.com <mailto:diane.fleming at gmail.com> >>> >>> From: Anne Gentle <anne at openstack.org <mailto:anne at openstack.org>> >>> >>> Date: Wednesday, May 21, 2014 8:48 AM >>> To: Christian Berendt <berendt at b1-systems.de >>> <mailto:berendt at b1-systems.de>> >>> Cc: "openstack-docs at lists.openstack.org >>> <mailto:openstack-docs at lists.openstack.org>" >>> <Openstack-docs at lists.openstack.org >>> <mailto:Openstack-docs at lists.openstack.org>> >>> >>> Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to >>> DocBook >>> >>> Glad you brought it up again. Last time someone asked a year ago, >>> here's how it went: >>> >>> http://lists.openstack.org/pipermail/openstack-docs/2013- >>> May/001630.html >>> >>> Seems like a recurring theme. Let's see what happens this time >>> around. >>> >>> Anne >>> >>> >>> On Wed, May 21, 2014 at 8:41 AM, Christian Berendt >>> <berendt at b1-systems.de <mailto:berendt at b1-systems.de>> wrote: >>> >>> Even I like AsciiDoc I would suggest to convert the HA guide from >>> AsciiDoc to DocBook. All other guides are written in DocBox and >>> I don't >>> see any benefit of keeping the HA guide in AsciiDoc. >>> >>> Christian. >>> >>> -- >>> Christian Berendt >>> Cloud Computing Solution Architect >>> Mail: berendt at b1-systems.de <mailto:berendt at b1-systems.de> >>> >>> >>> B1 Systems GmbH >>> Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de >>> GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: >>> Ingolstadt,HRB 3537 >>> >>> _______________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.openstack.org >>> <mailto:Openstack-docs at lists.openstack.org> >>> >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/ >>> openstack-docs >>> >>> >>> >>> _______________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.openstack.org >>> <mailto:Openstack-docs at lists.openstack.org> >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>> >>> >>> > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/b11f3eb6/attachment-0001.html> From nchase at mirantis.com Wed May 21 16:00:46 2014 From: nchase at mirantis.com (Nicholas Chase) Date: Wed, 21 May 2014 12:00:46 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> Message-ID: <537CCDAE.50305@mirantis.com> Only if I get to return the favor. :) ---- Nick On 5/21/2014 11:58 AM, Matt Kassawara wrote: > Shall we play pin the -1 on the patch? :) > > > On Wed, May 21, 2014 at 9:49 AM, Anne Gentle <anne at openstack.org > <mailto:anne at openstack.org>> wrote: > > Sounds good. If anyone has objections to the conversion, please > engage in the review. > Thanks, > Anne > > > On Wed, May 21, 2014 at 10:41 AM, Nicholas Chase > <nchase at mirantis.com <mailto:nchase at mirantis.com>> wrote: > > Will do! Give me a couple of days and it'll be in and ready for > review. > > ---- Nick > > > On 5/21/2014 11:21 AM, Diane Fleming wrote: > > Sure Nick, have at it! > > /Diane/ > /-----------------------------__-----------------/ > > Diane Fleming > Software Developer II - US > diane.fleming at rackspace.com <mailto:diane.fleming at rackspace.com> > Cell 512.323.6799 <tel:512.323.6799> > Office 512.874.1260 <tel:512.874.1260> > Skype drfleming0227 > Google-plus diane.fleming at gmail.com > <mailto:diane.fleming at gmail.com> > > From: Nick Chase <nchase at mirantis.com > <mailto:nchase at mirantis.com> <mailto:nchase at mirantis.com > <mailto:nchase at mirantis.com>>> > > Date: Wednesday, May 21, 2014 9:22 AM > To: Diane Fleming <diane.fleming at rackspace.com > <mailto:diane.fleming at rackspace.com> > <mailto:diane.fleming at __rackspace.com > <mailto:diane.fleming at rackspace.com>>> > Cc: Anne Gentle <anne at openstack.org > <mailto:anne at openstack.org> <mailto:anne at openstack.org > <mailto:anne at openstack.org>>>, > Christian Berendt <berendt at b1-systems.de > <mailto:berendt at b1-systems.de> > <mailto:berendt at b1-systems.de > <mailto:berendt at b1-systems.de>>__>, > "openstack-docs at lists.__openstack.org > <mailto:openstack-docs at lists.openstack.org> > <mailto:openstack-docs at lists.__openstack.org > <mailto:openstack-docs at lists.openstack.org>>" > <Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org> > <mailto:Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org>>> > > Subject: Re: [Openstack-docs] convert the HA guide from > AsciiDoc to DocBook > > I'd be happy to do the conversion; it's something I'm > familiar with, I > have blocks of time where I can do it, and Diane, you can be > more useful > doing stuff that I can't, as a rule. > > That said, if you're set on doing it yourself, I won't stop > you. :) > > Let me know. > > ---- Nick > > > On Wed, May 21, 2014 at 9:52 AM, Diane Fleming > <diane.fleming at rackspace.com > <mailto:diane.fleming at rackspace.com> > <mailto:diane.fleming at __rackspace.com > <mailto:diane.fleming at rackspace.com>>> wrote: > > Yes please! I'm happy to convert it if everyone agrees. > > > /Diane/ > /-----------------------------__-----------------/ > > Diane Fleming > Software Developer II - US > diane.fleming at rackspace.com > <mailto:diane.fleming at rackspace.com> > <mailto:diane.fleming at __rackspace.com > <mailto:diane.fleming at rackspace.com>> > Cell 512.323.6799 <tel:512.323.6799> <tel:512.323.6799 > <tel:512.323.6799>> > Office 512.874.1260 <tel:512.874.1260> > <tel:512.874.1260 <tel:512.874.1260>> > Skype drfleming0227 > Google-plus diane.fleming at gmail.com > <mailto:diane.fleming at gmail.com> > <mailto:diane.fleming at gmail.__com > <mailto:diane.fleming at gmail.com>> > > From: Anne Gentle <anne at openstack.org > <mailto:anne at openstack.org> <mailto:anne at openstack.org > <mailto:anne at openstack.org>>> > > Date: Wednesday, May 21, 2014 8:48 AM > To: Christian Berendt <berendt at b1-systems.de > <mailto:berendt at b1-systems.de> > <mailto:berendt at b1-systems.de > <mailto:berendt at b1-systems.de>>__> > Cc: "openstack-docs at lists.__openstack.org > <mailto:openstack-docs at lists.openstack.org> > <mailto:openstack-docs at lists.__openstack.org > <mailto:openstack-docs at lists.openstack.org>>" > <Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org> > <mailto:Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org>>> > > Subject: Re: [Openstack-docs] convert the HA guide from > AsciiDoc to > DocBook > > Glad you brought it up again. Last time someone asked a > year ago, > here's how it went: > > http://lists.openstack.org/__pipermail/openstack-docs/2013-__May/001630.html > <http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.html> > > Seems like a recurring theme. Let's see what happens > this time around. > > Anne > > > On Wed, May 21, 2014 at 8:41 AM, Christian Berendt > <berendt at b1-systems.de <mailto:berendt at b1-systems.de> > <mailto:berendt at b1-systems.de > <mailto:berendt at b1-systems.de>>__> wrote: > > Even I like AsciiDoc I would suggest to convert the > HA guide from > AsciiDoc to DocBook. All other guides are written > in DocBox and > I don't > see any benefit of keeping the HA guide in AsciiDoc. > > Christian. > > -- > Christian Berendt > Cloud Computing Solution Architect > Mail: berendt at b1-systems.de > <mailto:berendt at b1-systems.de> <mailto:berendt at b1-systems.de > <mailto:berendt at b1-systems.de>> > > > B1 Systems GmbH > Osterfeldstra?e 7 / 85088 Vohburg / > http://www.b1-systems.de > GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: > Ingolstadt,HRB 3537 > > _________________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org> > <mailto:Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org>> > > http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs > <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> > > > > _________________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org> > <mailto:Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org>> > http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs > <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> > > > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > <mailto:Openstack-docs at lists.openstack.org> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > From emilien.macchi at enovance.com Wed May 21 16:25:41 2014 From: emilien.macchi at enovance.com (Emilien Macchi) Date: Wed, 21 May 2014 18:25:41 +0200 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <537CCDAE.50305@mirantis.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> Message-ID: <537CD385.10102@enovance.com> +1 Emilien Macchi On Wed 21 May 2014 06:00:46 PM CEST, Nicholas Chase wrote: > Only if I get to return the favor. :) > > ---- Nick > > On 5/21/2014 11:58 AM, Matt Kassawara wrote: >> Shall we play pin the -1 on the patch? :) >> >> >> On Wed, May 21, 2014 at 9:49 AM, Anne Gentle <anne at openstack.org >> <mailto:anne at openstack.org>> wrote: >> >> Sounds good. If anyone has objections to the conversion, please >> engage in the review. >> Thanks, >> Anne >> >> >> On Wed, May 21, 2014 at 10:41 AM, Nicholas Chase >> <nchase at mirantis.com <mailto:nchase at mirantis.com>> wrote: >> >> Will do! Give me a couple of days and it'll be in and ready for >> review. >> >> ---- Nick >> >> >> On 5/21/2014 11:21 AM, Diane Fleming wrote: >> >> Sure Nick, have at it! >> >> /Diane/ >> /-----------------------------__-----------------/ >> >> Diane Fleming >> Software Developer II - US >> diane.fleming at rackspace.com >> <mailto:diane.fleming at rackspace.com> >> Cell 512.323.6799 <tel:512.323.6799> >> Office 512.874.1260 <tel:512.874.1260> >> Skype drfleming0227 >> Google-plus diane.fleming at gmail.com >> <mailto:diane.fleming at gmail.com> >> >> From: Nick Chase <nchase at mirantis.com >> <mailto:nchase at mirantis.com> <mailto:nchase at mirantis.com >> <mailto:nchase at mirantis.com>>> >> >> Date: Wednesday, May 21, 2014 9:22 AM >> To: Diane Fleming <diane.fleming at rackspace.com >> <mailto:diane.fleming at rackspace.com> >> <mailto:diane.fleming at __rackspace.com >> <mailto:diane.fleming at rackspace.com>>> >> Cc: Anne Gentle <anne at openstack.org >> <mailto:anne at openstack.org> <mailto:anne at openstack.org >> <mailto:anne at openstack.org>>>, >> Christian Berendt <berendt at b1-systems.de >> <mailto:berendt at b1-systems.de> >> <mailto:berendt at b1-systems.de >> <mailto:berendt at b1-systems.de>>__>, >> "openstack-docs at lists.__openstack.org >> <mailto:openstack-docs at lists.openstack.org> >> <mailto:openstack-docs at lists.__openstack.org >> <mailto:openstack-docs at lists.openstack.org>>" >> <Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org> >> <mailto:Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org>>> >> >> Subject: Re: [Openstack-docs] convert the HA guide from >> AsciiDoc to DocBook >> >> I'd be happy to do the conversion; it's something I'm >> familiar with, I >> have blocks of time where I can do it, and Diane, you can be >> more useful >> doing stuff that I can't, as a rule. >> >> That said, if you're set on doing it yourself, I won't stop >> you. :) >> >> Let me know. >> >> ---- Nick >> >> >> On Wed, May 21, 2014 at 9:52 AM, Diane Fleming >> <diane.fleming at rackspace.com >> <mailto:diane.fleming at rackspace.com> >> <mailto:diane.fleming at __rackspace.com >> <mailto:diane.fleming at rackspace.com>>> wrote: >> >> Yes please! I'm happy to convert it if everyone agrees. >> >> >> /Diane/ >> /-----------------------------__-----------------/ >> >> Diane Fleming >> Software Developer II - US >> diane.fleming at rackspace.com >> <mailto:diane.fleming at rackspace.com> >> <mailto:diane.fleming at __rackspace.com >> <mailto:diane.fleming at rackspace.com>> >> Cell 512.323.6799 <tel:512.323.6799> <tel:512.323.6799 >> <tel:512.323.6799>> >> Office 512.874.1260 <tel:512.874.1260> >> <tel:512.874.1260 <tel:512.874.1260>> >> Skype drfleming0227 >> Google-plus diane.fleming at gmail.com >> <mailto:diane.fleming at gmail.com> >> <mailto:diane.fleming at gmail.__com >> <mailto:diane.fleming at gmail.com>> >> >> From: Anne Gentle <anne at openstack.org >> <mailto:anne at openstack.org> <mailto:anne at openstack.org >> <mailto:anne at openstack.org>>> >> >> Date: Wednesday, May 21, 2014 8:48 AM >> To: Christian Berendt <berendt at b1-systems.de >> <mailto:berendt at b1-systems.de> >> <mailto:berendt at b1-systems.de >> <mailto:berendt at b1-systems.de>>__> >> Cc: "openstack-docs at lists.__openstack.org >> <mailto:openstack-docs at lists.openstack.org> >> <mailto:openstack-docs at lists.__openstack.org >> <mailto:openstack-docs at lists.openstack.org>>" >> <Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org> >> <mailto:Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org>>> >> >> Subject: Re: [Openstack-docs] convert the HA guide from >> AsciiDoc to >> DocBook >> >> Glad you brought it up again. Last time someone asked a >> year ago, >> here's how it went: >> >> >> http://lists.openstack.org/__pipermail/openstack-docs/2013-__May/001630.html >> >> >> <http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.html> >> >> >> Seems like a recurring theme. Let's see what happens >> this time around. >> >> Anne >> >> >> On Wed, May 21, 2014 at 8:41 AM, Christian Berendt >> <berendt at b1-systems.de <mailto:berendt at b1-systems.de> >> <mailto:berendt at b1-systems.de >> <mailto:berendt at b1-systems.de>>__> wrote: >> >> Even I like AsciiDoc I would suggest to convert the >> HA guide from >> AsciiDoc to DocBook. All other guides are written >> in DocBox and >> I don't >> see any benefit of keeping the HA guide in >> AsciiDoc. >> >> Christian. >> >> -- >> Christian Berendt >> Cloud Computing Solution Architect >> Mail: berendt at b1-systems.de >> <mailto:berendt at b1-systems.de> <mailto:berendt at b1-systems.de >> <mailto:berendt at b1-systems.de>> >> >> >> B1 Systems GmbH >> Osterfeldstra?e 7 / 85088 Vohburg / >> http://www.b1-systems.de >> GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: >> Ingolstadt,HRB 3537 >> >> _________________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org> >> <mailto:Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org>> >> >> >> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs >> >> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> >> >> >> >> _________________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org> >> <mailto:Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org>> >> >> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs >> >> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> >> >> >> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> <mailto:Openstack-docs at lists.openstack.org> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 555 bytes Desc: OpenPGP digital signature URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/f0d7941e/attachment.pgp> From aj at suse.com Wed May 21 17:49:08 2014 From: aj at suse.com (Andreas Jaeger) Date: Wed, 21 May 2014 19:49:08 +0200 Subject: [Openstack-docs] database-api publishing - ready for index.html? Message-ID: <537CE714.2000301@suse.com> The database-api is now publishing: http://docs.openstack.org/api/openstack-databases/content/overview.html Is this ready to get added to the index.html pages - or are there changes needed like removing the "review" from it? Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From annegentle at justwriteclick.com Wed May 21 18:39:25 2014 From: annegentle at justwriteclick.com (Anne Gentle) Date: Wed, 21 May 2014 13:39:25 -0500 Subject: [Openstack-docs] new contributor needs git-review setup assistance In-Reply-To: <65E82A781FA20A4D81EF9EA3F17C8E737812E9@G1W3641.americas.hpqcorp.net> References: <65E82A781FA20A4D81EF9EA3F17C8E737812E9@G1W3641.americas.hpqcorp.net> Message-ID: <C07725DE-4BDF-4D52-B66F-5E3780A45594@justwriteclick.com> On Windows, you do have to follow those steps. I have helped a fair share of people - can you give a little more info about what you see when you try to run python? You can ask more here and we'll help you through it. It probably means we have to get a working Python install on your Windows environment which is many steps. Anne Gentle Content Stacker anne at openstack.org > On May 21, 2014, at 4:37 AM, "Marino, Lisa Michele" <lisa.m.marino at hp.com> wrote: > > HI there, > > I have just joined as a contributor and was following the repo setup instructions here: > https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers > > I got hung up on the install git-review step, specifically ?python setup.py install? command. Is there anyone who can help me with this? > > Thanks! > Lsisa > > > > Lisa Michele Marino > Information Developer > HP Helion > > lisa.m.marino at hp.com > T 001 + 412-307-4992 > M 001 + 919-931-3165 > Hewlett-Packard Company > 5097 W Harbison Rd > Pittsburgh PA 15205 > USA > > <image001.png> > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/ddd10f1e/attachment-0001.html> From joseph.robinson at RACKSPACE.COM Wed May 21 22:59:39 2014 From: joseph.robinson at RACKSPACE.COM (Joseph Robinson) Date: Wed, 21 May 2014 22:59:39 +0000 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <537CD385.10102@enovance.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> Message-ID: <CFA36D4C.1217%joseph.robinson@rackspace.com> +1 , One point though - I am working on a patch to the HA guide at the moment. I will complete it ASAP so the conversion to XML can start. My patch: https://review.openstack.org/#/c/93856/2 -Joseph Robinson On 22/05/2014 2:25 am, "Emilien Macchi" <emilien.macchi at enovance.com> wrote: >+1 > >Emilien Macchi > >On Wed 21 May 2014 06:00:46 PM CEST, Nicholas Chase wrote: >> Only if I get to return the favor. :) >> >> ---- Nick >> >> On 5/21/2014 11:58 AM, Matt Kassawara wrote: >>> Shall we play pin the -1 on the patch? :) >>> >>> >>> On Wed, May 21, 2014 at 9:49 AM, Anne Gentle <anne at openstack.org >>> <mailto:anne at openstack.org>> wrote: >>> >>> Sounds good. If anyone has objections to the conversion, please >>> engage in the review. >>> Thanks, >>> Anne >>> >>> >>> On Wed, May 21, 2014 at 10:41 AM, Nicholas Chase >>> <nchase at mirantis.com <mailto:nchase at mirantis.com>> wrote: >>> >>> Will do! Give me a couple of days and it'll be in and ready >>>for >>> review. >>> >>> ---- Nick >>> >>> >>> On 5/21/2014 11:21 AM, Diane Fleming wrote: >>> >>> Sure Nick, have at it! >>> >>> /Diane/ >>> /-----------------------------__-----------------/ >>> >>> Diane Fleming >>> Software Developer II - US >>> diane.fleming at rackspace.com >>> <mailto:diane.fleming at rackspace.com> >>> Cell 512.323.6799 <tel:512.323.6799> >>> Office 512.874.1260 <tel:512.874.1260> >>> Skype drfleming0227 >>> Google-plus diane.fleming at gmail.com >>> <mailto:diane.fleming at gmail.com> >>> >>> From: Nick Chase <nchase at mirantis.com >>> <mailto:nchase at mirantis.com> <mailto:nchase at mirantis.com >>> <mailto:nchase at mirantis.com>>> >>> >>> Date: Wednesday, May 21, 2014 9:22 AM >>> To: Diane Fleming <diane.fleming at rackspace.com >>> <mailto:diane.fleming at rackspace.com> >>> <mailto:diane.fleming at __rackspace.com >>> <mailto:diane.fleming at rackspace.com>>> >>> Cc: Anne Gentle <anne at openstack.org >>> <mailto:anne at openstack.org> <mailto:anne at openstack.org >>> <mailto:anne at openstack.org>>>, >>> Christian Berendt <berendt at b1-systems.de >>> <mailto:berendt at b1-systems.de> >>> <mailto:berendt at b1-systems.de >>> <mailto:berendt at b1-systems.de>>__>, >>> "openstack-docs at lists.__openstack.org >>> <mailto:openstack-docs at lists.openstack.org> >>> <mailto:openstack-docs at lists.__openstack.org >>> <mailto:openstack-docs at lists.openstack.org>>" >>> <Openstack-docs at lists.__openstack.org >>> <mailto:Openstack-docs at lists.openstack.org> >>> <mailto:Openstack-docs at lists.__openstack.org >>> <mailto:Openstack-docs at lists.openstack.org>>> >>> >>> Subject: Re: [Openstack-docs] convert the HA guide from >>> AsciiDoc to DocBook >>> >>> I'd be happy to do the conversion; it's something I'm >>> familiar with, I >>> have blocks of time where I can do it, and Diane, you can >>>be >>> more useful >>> doing stuff that I can't, as a rule. >>> >>> That said, if you're set on doing it yourself, I won't stop >>> you. :) >>> >>> Let me know. >>> >>> ---- Nick >>> >>> >>> On Wed, May 21, 2014 at 9:52 AM, Diane Fleming >>> <diane.fleming at rackspace.com >>> <mailto:diane.fleming at rackspace.com> >>> <mailto:diane.fleming at __rackspace.com >>> <mailto:diane.fleming at rackspace.com>>> wrote: >>> >>> Yes please! I'm happy to convert it if everyone >>>agrees. >>> >>> >>> /Diane/ >>> /-----------------------------__-----------------/ >>> >>> Diane Fleming >>> Software Developer II - US >>> diane.fleming at rackspace.com >>> <mailto:diane.fleming at rackspace.com> >>> <mailto:diane.fleming at __rackspace.com >>> <mailto:diane.fleming at rackspace.com>> >>> Cell 512.323.6799 <tel:512.323.6799> <tel:512.323.6799 >>> <tel:512.323.6799>> >>> Office 512.874.1260 <tel:512.874.1260> >>> <tel:512.874.1260 <tel:512.874.1260>> >>> Skype drfleming0227 >>> Google-plus diane.fleming at gmail.com >>> <mailto:diane.fleming at gmail.com> >>> <mailto:diane.fleming at gmail.__com >>> <mailto:diane.fleming at gmail.com>> >>> >>> From: Anne Gentle <anne at openstack.org >>> <mailto:anne at openstack.org> <mailto:anne at openstack.org >>> <mailto:anne at openstack.org>>> >>> >>> Date: Wednesday, May 21, 2014 8:48 AM >>> To: Christian Berendt <berendt at b1-systems.de >>> <mailto:berendt at b1-systems.de> >>> <mailto:berendt at b1-systems.de >>> <mailto:berendt at b1-systems.de>>__> >>> Cc: "openstack-docs at lists.__openstack.org >>> <mailto:openstack-docs at lists.openstack.org> >>> <mailto:openstack-docs at lists.__openstack.org >>> <mailto:openstack-docs at lists.openstack.org>>" >>> <Openstack-docs at lists.__openstack.org >>> <mailto:Openstack-docs at lists.openstack.org> >>> <mailto:Openstack-docs at lists.__openstack.org >>> <mailto:Openstack-docs at lists.openstack.org>>> >>> >>> Subject: Re: [Openstack-docs] convert the HA guide >>>from >>> AsciiDoc to >>> DocBook >>> >>> Glad you brought it up again. Last time someone asked >>>a >>> year ago, >>> here's how it went: >>> >>> >>> >>>http://lists.openstack.org/__pipermail/openstack-docs/2013-__May/001630. >>>html >>> >>> >>> >>><http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.htm >>>l> >>> >>> >>> Seems like a recurring theme. Let's see what happens >>> this time around. >>> >>> Anne >>> >>> >>> On Wed, May 21, 2014 at 8:41 AM, Christian Berendt >>> <berendt at b1-systems.de <mailto:berendt at b1-systems.de> >>> <mailto:berendt at b1-systems.de >>> <mailto:berendt at b1-systems.de>>__> wrote: >>> >>> Even I like AsciiDoc I would suggest to convert >>>the >>> HA guide from >>> AsciiDoc to DocBook. All other guides are written >>> in DocBox and >>> I don't >>> see any benefit of keeping the HA guide in >>> AsciiDoc. >>> >>> Christian. >>> >>> -- >>> Christian Berendt >>> Cloud Computing Solution Architect >>> Mail: berendt at b1-systems.de >>> <mailto:berendt at b1-systems.de> >>><mailto:berendt at b1-systems.de >>> <mailto:berendt at b1-systems.de>> >>> >>> >>> B1 Systems GmbH >>> Osterfeldstra?e 7 / 85088 Vohburg / >>> http://www.b1-systems.de >>> GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: >>> Ingolstadt,HRB 3537 >>> >>> _________________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.__openstack.org >>> <mailto:Openstack-docs at lists.openstack.org> >>> <mailto:Openstack-docs at lists.__openstack.org >>> <mailto:Openstack-docs at lists.openstack.org>> >>> >>> >>> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs >>> >>> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> >>> >>> >>> >>> _________________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.__openstack.org >>> <mailto:Openstack-docs at lists.openstack.org> >>> <mailto:Openstack-docs at lists.__openstack.org >>> <mailto:Openstack-docs at lists.openstack.org>> >>> >>> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs >>> >>> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> >>> >>> >>> >>> >>> _______________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.openstack.org >>> <mailto:Openstack-docs at lists.openstack.org> >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>> >>> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > From jidawanghao at 163.com Thu May 22 07:06:28 2014 From: jidawanghao at 163.com (1) Date: Thu, 22 May 2014 15:06:28 +0800 (CST) Subject: [Openstack-docs] one question ,and some errors you got Message-ID: <5ca52de8.7998.14622c0a25c.Coremail.jidawanghao@163.com> one question Perhaps, I didn't understand why shall we change the IP address of both eth0 and eth1, with this action , the compute1 node may not have the acceptable to keep conncetion with the external networking , and most important of all, it may be influence the apt-get install action or apt-get update or ap-get upgrade action. Need anyone's reply. One fans coming from China, Peony city. some errors I found, but I'm angry about your website's action to delete my comment written in Chinese. ????8??????/etc/ntp.conf?????server?? ?9??OpenStack packages,3. ???????????key???????key????? gpg ?keyserver pgpkeys.mit.edu ?recv-key ???key???64AA94D00B849883? gpg ?a ?export???key???64AA94D00B849883? | apt-key add - ?11??20???????????????????????????????????? ?29??For example: #glance image-create ?name=?CirrOS 0.3.1? ?disk-format=qcow2 \--container-format=bare ?is-public=true < cirros-0.3.1-x86_64-disk.img ????????????HTTP 500?????????27?2. Respond to prompts for database management????????You must also select the caching type.???????You must select the caching type.????????caching?????????keystone????????????????????????/etc/glance/api.conf?/etc/glance/registry.conf??debug = true?????????????/var/log/glance/api.log?/var/log/glance/registry.log? -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140522/13c3c2ac/attachment.html> From aj at suse.com Thu May 22 15:01:05 2014 From: aj at suse.com (Andreas Jaeger) Date: Thu, 22 May 2014 17:01:05 +0200 Subject: [Openstack-docs] Japanese Security Guide fails to build Message-ID: <537E1131.2070706@suse.com> We now check the translations in the gate and I noticed that the Security Guide fails to build: https://bugs.launchpad.net/openstack-i18n/+bug/1322224 This looks some tools issue, any help on how to fix this is welcome! Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Thu May 22 15:11:02 2014 From: aj at suse.com (Andreas Jaeger) Date: Thu, 22 May 2014 17:11:02 +0200 Subject: [Openstack-docs] one question ,and some errors you got In-Reply-To: <5ca52de8.7998.14622c0a25c.Coremail.jidawanghao@163.com> References: <5ca52de8.7998.14622c0a25c.Coremail.jidawanghao@163.com> Message-ID: <537E1386.4020605@suse.com> On 05/22/2014 09:06 AM, 1 wrote: > one question > Perhaps, I didn't understand why shall we change the IP address of both > eth0 and eth1, with this action , the compute1 node may not have the > acceptable to keep conncetion with the external networking , and most > important of all, it may be influence the apt-get install action or > apt-get update or ap-get upgrade action. Need anyone's reply. One fans > coming from China, Peony city. > > some errors I found, but I'm angry about your website's action to delete > my comment written in Chinese. It wasn't the website, it was me. I didn't think you really wanted to tell everybody your phone number and non-English comments will not help you at all, since most of us cant't read them, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Thu May 22 18:55:32 2014 From: aj at suse.com (Andreas Jaeger) Date: Thu, 22 May 2014 20:55:32 +0200 Subject: [Openstack-docs] [Openstack-i18n] Translation gate for doc jobs In-Reply-To: <537A42FA.4000302@suse.com> References: <5375284F.3030208@suse.com> <CAD0KtVFooB-KqsYe82Rm1kQ0qVimv8asDK7Sd3COHUWBzVD6Pg@mail.gmail.com> <537A42FA.4000302@suse.com> Message-ID: <537E4824.7090701@suse.com> The jobs are running, and I've started documenting this here: https://wiki.openstack.org/wiki/Documentation/Builds#Gates Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Thu May 22 20:49:11 2014 From: anne at openstack.org (Anne Gentle) Date: Thu, 22 May 2014 15:49:11 -0500 Subject: [Openstack-docs] database-api publishing - ready for index.html? In-Reply-To: <537CE714.2000301@suse.com> References: <537CE714.2000301@suse.com> Message-ID: <CAD0KtVEbXv+q=Xhwo4zM_64CZanfFq7B-SFGdqUOANjnLkbDqg@mail.gmail.com> Hi Andreas, The trove team wanted to move the source from database-api to their trove repo. I'd like to publish after that happens if possible. They can better keep their examples updated this way. Did someone request the build from database-api? The "review" watermark makes me think that the move should happen by the team so they can ensure that accurate information is being published. Any insights on the request and timing? Thanks, Anne On Wed, May 21, 2014 at 12:49 PM, Andreas Jaeger <aj at suse.com> wrote: > The database-api is now publishing: > > http://docs.openstack.org/api/openstack-databases/content/overview.html > > Is this ready to get added to the index.html pages - or are there > changes needed like removing the "review" from it? > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140522/4e30b39e/attachment.html> From nikhil at manchanda.me Thu May 22 22:06:17 2014 From: nikhil at manchanda.me (Nikhil Manchanda) Date: Thu, 22 May 2014 18:06:17 -0400 Subject: [Openstack-docs] database-api publishing - ready for index.html? In-Reply-To: <CAD0KtVEbXv+q=Xhwo4zM_64CZanfFq7B-SFGdqUOANjnLkbDqg@mail.gmail.com> References: <537CE714.2000301@suse.com> <CAD0KtVEbXv+q=Xhwo4zM_64CZanfFq7B-SFGdqUOANjnLkbDqg@mail.gmail.com> Message-ID: <CAMt+b=mmHsb6=LR1dx7HnkK6YrsVg7JTEn3S=Di+85p8x23BLw@mail.gmail.com> Hi Anne / Andreas: The trove team (thanks to Tim! (grapex)) has already landed the change to move the api-docs from the openstack/database-api to the openstack/trove repository. Andreas can you please clarify if the docs in this review are being built from the trove repository, or the older database-api repository? If it's the former, I think we are good. Of course, I still need to get myself and a couple of other folks from Trove to go over the docs, and update it with new APIs that we have recently added (datastore / config groups). :) Still working on that. Thanks, Nikhil On Thu, May 22, 2014 at 4:49 PM, Anne Gentle <anne at openstack.org> wrote: > Hi Andreas, > > The trove team wanted to move the source from database-api to their trove > repo. I'd like to publish after that happens if possible. They can better > keep their examples updated this way. Did someone request the build from > database-api? > > The "review" watermark makes me think that the move should happen by the > team so they can ensure that accurate information is being published. Any > insights on the request and timing? > Thanks, > Anne > > > On Wed, May 21, 2014 at 12:49 PM, Andreas Jaeger <aj at suse.com> wrote: > >> The database-api is now publishing: >> >> http://docs.openstack.org/api/openstack-databases/content/overview.html >> >> Is this ready to get added to the index.html pages - or are there >> changes needed like removing the "review" from it? >> >> Andreas >> -- >> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany >> GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140522/b1198922/attachment.html> From mkassawara at gmail.com Thu May 22 23:58:38 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Thu, 22 May 2014 17:58:38 -0600 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs Message-ID: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> I found some inconsistencies with filenames and chapter/section IDs while auditing the Installation Guide. I thought I found some conventions while updating the guide for Icehouse, but can't find them now. If they exist, can someone point me to them? If not, we should develop some so we can proceed with the improvements. -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140522/b3805466/attachment.html> From aj at suse.com Fri May 23 07:13:28 2014 From: aj at suse.com (Andreas Jaeger) Date: Fri, 23 May 2014 09:13:28 +0200 Subject: [Openstack-docs] database-api publishing - ready for index.html? In-Reply-To: <CAMt+b=mmHsb6=LR1dx7HnkK6YrsVg7JTEn3S=Di+85p8x23BLw@mail.gmail.com> References: <537CE714.2000301@suse.com> <CAD0KtVEbXv+q=Xhwo4zM_64CZanfFq7B-SFGdqUOANjnLkbDqg@mail.gmail.com> <CAMt+b=mmHsb6=LR1dx7HnkK6YrsVg7JTEn3S=Di+85p8x23BLw@mail.gmail.com> Message-ID: <537EF518.5000107@suse.com> On 05/23/2014 12:06 AM, Nikhil Manchanda wrote: > Hi Anne / Andreas: > > The trove team (thanks to Tim! (grapex)) has already landed the change > to move the api-docs from the openstack/database-api to the > openstack/trove repository. Andreas can you please clarify if the docs > in this review are being built from the trove repository, or the older > database-api repository? This is from openstack/trove repository, we never published database-api repository. > If it's the former, I think we are good. Btw. I just send a patch to clean up the pom: https://review.openstack.org/94989 This removes the REVIEW and the hardcoded publishing date, > Of course, I still need to get myself and a couple of other folks from > Trove to go over the docs, and update it with new APIs that we have > recently added (datastore / config groups). :) Still working on that. It also only talks about MySQL - AFAIK you support other databases as well now, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From diane.fleming at RACKSPACE.COM Fri May 23 12:45:48 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Fri, 23 May 2014 12:45:48 +0000 Subject: [Openstack-docs] database-api publishing - ready for index.html? In-Reply-To: <537EF518.5000107@suse.com> References: <537CE714.2000301@suse.com> <CAD0KtVEbXv+q=Xhwo4zM_64CZanfFq7B-SFGdqUOANjnLkbDqg@mail.gmail.com> <CAMt+b=mmHsb6=LR1dx7HnkK6YrsVg7JTEn3S=Di+85p8x23BLw@mail.gmail.com>, <537EF518.5000107@suse.com> Message-ID: <A89BAF7C-F198-4784-A144-C9E0A9920B68@RACKSPACE.COM> Can we remove database-api? Sent from my iPhone > On May 23, 2014, at 2:15 AM, "Andreas Jaeger" <aj at suse.com> wrote: > >> On 05/23/2014 12:06 AM, Nikhil Manchanda wrote: >> Hi Anne / Andreas: >> >> The trove team (thanks to Tim! (grapex)) has already landed the change >> to move the api-docs from the openstack/database-api to the >> openstack/trove repository. Andreas can you please clarify if the docs >> in this review are being built from the trove repository, or the older >> database-api repository? > > This is from openstack/trove repository, we never published database-api > repository. > >> If it's the former, I think we are good. > > Btw. I just send a patch to clean up the pom: > https://review.openstack.org/94989 > > This removes the REVIEW and the hardcoded publishing date, > >> Of course, I still need to get myself and a couple of other folks from >> Trove to go over the docs, and update it with new APIs that we have >> recently added (datastore / config groups). :) Still working on that. > > It also only talks about MySQL - AFAIK you support other databases as > well now, > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs From aj at suse.com Fri May 23 12:51:48 2014 From: aj at suse.com (Andreas Jaeger) Date: Fri, 23 May 2014 14:51:48 +0200 Subject: [Openstack-docs] database-api publishing - ready for index.html? In-Reply-To: <A89BAF7C-F198-4784-A144-C9E0A9920B68@RACKSPACE.COM> References: <537CE714.2000301@suse.com> <CAD0KtVEbXv+q=Xhwo4zM_64CZanfFq7B-SFGdqUOANjnLkbDqg@mail.gmail.com> <CAMt+b=mmHsb6=LR1dx7HnkK6YrsVg7JTEn3S=Di+85p8x23BLw@mail.gmail.com>, <537EF518.5000107@suse.com> <A89BAF7C-F198-4784-A144-C9E0A9920B68@RACKSPACE.COM> Message-ID: <537F4464.2030809@suse.com> On 05/23/2014 02:45 PM, Diane Fleming wrote: > Can we remove database-api? Yes, the repository will be moved to the attic as part of the big rename: https://review.openstack.org/94953 Andreas > Sent from my iPhone > >> On May 23, 2014, at 2:15 AM, "Andreas Jaeger" <aj at suse.com> wrote: >> >>> On 05/23/2014 12:06 AM, Nikhil Manchanda wrote: >>> Hi Anne / Andreas: >>> >>> The trove team (thanks to Tim! (grapex)) has already landed the change >>> to move the api-docs from the openstack/database-api to the >>> openstack/trove repository. Andreas can you please clarify if the docs >>> in this review are being built from the trove repository, or the older >>> database-api repository? >> >> This is from openstack/trove repository, we never published database-api >> repository. >> >>> If it's the former, I think we are good. >> >> Btw. I just send a patch to clean up the pom: >> https://review.openstack.org/94989 >> >> This removes the REVIEW and the hardcoded publishing date, >> >>> Of course, I still need to get myself and a couple of other folks from >>> Trove to go over the docs, and update it with new APIs that we have >>> recently added (datastore / config groups). :) Still working on that. >> >> It also only talks about MySQL - AFAIK you support other databases as >> well now, >> >> Andreas >> -- >> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany >> GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Fri May 23 13:03:25 2014 From: anne at openstack.org (Anne Gentle) Date: Fri, 23 May 2014 08:03:25 -0500 Subject: [Openstack-docs] database-api publishing - ready for index.html? In-Reply-To: <537F4464.2030809@suse.com> References: <537CE714.2000301@suse.com> <CAD0KtVEbXv+q=Xhwo4zM_64CZanfFq7B-SFGdqUOANjnLkbDqg@mail.gmail.com> <CAMt+b=mmHsb6=LR1dx7HnkK6YrsVg7JTEn3S=Di+85p8x23BLw@mail.gmail.com> <537EF518.5000107@suse.com> <A89BAF7C-F198-4784-A144-C9E0A9920B68@RACKSPACE.COM> <537F4464.2030809@suse.com> Message-ID: <CAD0KtVF1LaSyodUWCTo_O4VoQQpC4hDd0tRCkP86GGK9R3FyKQ@mail.gmail.com> On Fri, May 23, 2014 at 7:51 AM, Andreas Jaeger <aj at suse.com> wrote: > On 05/23/2014 02:45 PM, Diane Fleming wrote: > > Can we remove database-api? > > Yes, the repository will be moved to the attic as part of the big rename: > https://review.openstack.org/94953 > > Thanks for all of this, Andreas and Nikhil! Nice work. > Andreas > > > Sent from my iPhone > > > >> On May 23, 2014, at 2:15 AM, "Andreas Jaeger" <aj at suse.com> wrote: > >> > >>> On 05/23/2014 12:06 AM, Nikhil Manchanda wrote: > >>> Hi Anne / Andreas: > >>> > >>> The trove team (thanks to Tim! (grapex)) has already landed the change > >>> to move the api-docs from the openstack/database-api to the > >>> openstack/trove repository. Andreas can you please clarify if the docs > >>> in this review are being built from the trove repository, or the older > >>> database-api repository? > >> > >> This is from openstack/trove repository, we never published database-api > >> repository. > >> > >>> If it's the former, I think we are good. > >> > >> Btw. I just send a patch to clean up the pom: > >> https://review.openstack.org/94989 > >> > >> This removes the REVIEW and the hardcoded publishing date, > >> > >>> Of course, I still need to get myself and a couple of other folks from > >>> Trove to go over the docs, and update it with new APIs that we have > >>> recently added (datastore / config groups). :) Still working on that. > >> > >> It also only talks about MySQL - AFAIK you support other databases as > >> well now, > >> > >> Andreas > >> -- > >> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi > >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > >> GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > >> > >> _______________________________________________ > >> Openstack-docs mailing list > >> Openstack-docs at lists.openstack.org > >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > > > > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140523/f3e7e14f/attachment.html> From aj at suse.com Fri May 23 19:15:51 2014 From: aj at suse.com (Andreas Jaeger) Date: Fri, 23 May 2014 21:15:51 +0200 Subject: [Openstack-docs] Target audience In-Reply-To: <537A6C5D.9090600@suse.com> References: <537A6C5D.9090600@suse.com> Message-ID: <537F9E67.7000609@suse.com> Here's a next iteration for content - I've put it up on an etherpad for easier editing: https://etherpad.openstack.org/p/target_audience For the wiki, I would add something like the following - and if we agree on this, we can refine the target audience for each book. For writing these books, we use some simple personas: Anna the admin Anna is an administrator who is responsible for maintaining (and securing) the OpenStack cloud installation. She has many years of experience with Linux systems administration. Darren the deployer Darren is responsible for doing the initial OpenStack deployment on the host machines. Emile the end-user Emile uses the cloud to do software development inside of the virtual machines. She uses the command-line tools because she finds it quicker than using the dashboard. Otto, the devops operator Otto is the application devops operator, he runs and monitors applications in the cloud. Manual breakdown: Operations Guide Cloud Administrator Guide Admin User Guide These guides target the day to day operations of an OpenStack cloud system. Persona: Anna ------------------------ Configuration Reference HA Guide Install Guide Operations Guide These guides target cloud administrators who sets up an OpenStack cloud and configures the OpenStack services. Persona: Darren, Anna ------------------------ Security Guide This guide targets the Security Administrator of a cloud team and can be referenced to harden existing OpenStack deployments or to evaluate the security controls of OpenStack cloud providers. Persona: Anna ------------------------ End User Guide Image Guide Persona: Emile -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From mkassawara at gmail.com Sat May 24 14:45:21 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Sat, 24 May 2014 08:45:21 -0600 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> References: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> Message-ID: <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> Would consistently indicating type within an ID help clarify references? For example, chapter IDs always start with "ch_", section IDs always start with "sec_", figure IDs start with "fig_", etc. On Thu, May 22, 2014 at 5:58 PM, Matt Kassawara <mkassawara at gmail.com>wrote: > I found some inconsistencies with filenames and chapter/section IDs while > auditing the Installation Guide. I thought I found some conventions while > updating the guide for Icehouse, but can't find them now. If they exist, > can someone point me to them? If not, we should develop some so we can > proceed with the improvements. > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140524/1d209fbd/attachment.html> From nchase at mirantis.com Sun May 25 00:16:34 2014 From: nchase at mirantis.com (Nick Chase) Date: Sat, 24 May 2014 20:16:34 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CFA36D4C.1217%joseph.robinson@rackspace.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> Message-ID: <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> I'll get started on the structure and the rest of the chapters in the meantime. Question, though: I'd hate to try and put this through as one huge review; I'm thinking instead maybe one bug for the general changeover, then one bug each per chapter? I can have everything ready to go to start, and once the book framework's been merged, we can run the chapter reviews concurrently to minimize disruption. Locally, I've already got the framework in and I'm adding chapters (keeping in mind that I'll have to re-add Joseph's content when he's finished). Thoughts? ---- Nick On Wed, May 21, 2014 at 6:59 PM, Joseph Robinson < joseph.robinson at rackspace.com> wrote: > +1 , One point though - I am working on a patch to the HA guide at the > moment. I will complete it ASAP so the conversion to XML can start. > > My patch: https://review.openstack.org/#/c/93856/2 > > -Joseph Robinson > > On 22/05/2014 2:25 am, "Emilien Macchi" <emilien.macchi at enovance.com> > wrote: > > >+1 > > > >Emilien Macchi > > > >On Wed 21 May 2014 06:00:46 PM CEST, Nicholas Chase wrote: > >> Only if I get to return the favor. :) > >> > >> ---- Nick > >> > >> On 5/21/2014 11:58 AM, Matt Kassawara wrote: > >>> Shall we play pin the -1 on the patch? :) > >>> > >>> > >>> On Wed, May 21, 2014 at 9:49 AM, Anne Gentle <anne at openstack.org > >>> <mailto:anne at openstack.org>> wrote: > >>> > >>> Sounds good. If anyone has objections to the conversion, please > >>> engage in the review. > >>> Thanks, > >>> Anne > >>> > >>> > >>> On Wed, May 21, 2014 at 10:41 AM, Nicholas Chase > >>> <nchase at mirantis.com <mailto:nchase at mirantis.com>> wrote: > >>> > >>> Will do! Give me a couple of days and it'll be in and ready > >>>for > >>> review. > >>> > >>> ---- Nick > >>> > >>> > >>> On 5/21/2014 11:21 AM, Diane Fleming wrote: > >>> > >>> Sure Nick, have at it! > >>> > >>> /Diane/ > >>> /-----------------------------__-----------------/ > >>> > >>> Diane Fleming > >>> Software Developer II - US > >>> diane.fleming at rackspace.com > >>> <mailto:diane.fleming at rackspace.com> > >>> Cell 512.323.6799 <tel:512.323.6799> > >>> Office 512.874.1260 <tel:512.874.1260> > >>> Skype drfleming0227 > >>> Google-plus diane.fleming at gmail.com > >>> <mailto:diane.fleming at gmail.com> > >>> > >>> From: Nick Chase <nchase at mirantis.com > >>> <mailto:nchase at mirantis.com> <mailto:nchase at mirantis.com > >>> <mailto:nchase at mirantis.com>>> > >>> > >>> Date: Wednesday, May 21, 2014 9:22 AM > >>> To: Diane Fleming <diane.fleming at rackspace.com > >>> <mailto:diane.fleming at rackspace.com> > >>> <mailto:diane.fleming at __rackspace.com > >>> <mailto:diane.fleming at rackspace.com>>> > >>> Cc: Anne Gentle <anne at openstack.org > >>> <mailto:anne at openstack.org> <mailto:anne at openstack.org > >>> <mailto:anne at openstack.org>>>, > >>> Christian Berendt <berendt at b1-systems.de > >>> <mailto:berendt at b1-systems.de> > >>> <mailto:berendt at b1-systems.de > >>> <mailto:berendt at b1-systems.de>>__>, > >>> "openstack-docs at lists.__openstack.org > >>> <mailto:openstack-docs at lists.openstack.org> > >>> <mailto:openstack-docs at lists.__openstack.org > >>> <mailto:openstack-docs at lists.openstack.org>>" > >>> <Openstack-docs at lists.__openstack.org > >>> <mailto:Openstack-docs at lists.openstack.org> > >>> <mailto:Openstack-docs at lists.__openstack.org > >>> <mailto:Openstack-docs at lists.openstack.org>>> > >>> > >>> Subject: Re: [Openstack-docs] convert the HA guide from > >>> AsciiDoc to DocBook > >>> > >>> I'd be happy to do the conversion; it's something I'm > >>> familiar with, I > >>> have blocks of time where I can do it, and Diane, you can > >>>be > >>> more useful > >>> doing stuff that I can't, as a rule. > >>> > >>> That said, if you're set on doing it yourself, I won't stop > >>> you. :) > >>> > >>> Let me know. > >>> > >>> ---- Nick > >>> > >>> > >>> On Wed, May 21, 2014 at 9:52 AM, Diane Fleming > >>> <diane.fleming at rackspace.com > >>> <mailto:diane.fleming at rackspace.com> > >>> <mailto:diane.fleming at __rackspace.com > >>> <mailto:diane.fleming at rackspace.com>>> wrote: > >>> > >>> Yes please! I'm happy to convert it if everyone > >>>agrees. > >>> > >>> > >>> /Diane/ > >>> /-----------------------------__-----------------/ > >>> > >>> Diane Fleming > >>> Software Developer II - US > >>> diane.fleming at rackspace.com > >>> <mailto:diane.fleming at rackspace.com> > >>> <mailto:diane.fleming at __rackspace.com > >>> <mailto:diane.fleming at rackspace.com>> > >>> Cell 512.323.6799 <tel:512.323.6799> <tel: > 512.323.6799 > >>> <tel:512.323.6799>> > >>> Office 512.874.1260 <tel:512.874.1260> > >>> <tel:512.874.1260 <tel:512.874.1260>> > >>> Skype drfleming0227 > >>> Google-plus diane.fleming at gmail.com > >>> <mailto:diane.fleming at gmail.com> > >>> <mailto:diane.fleming at gmail.__com > >>> <mailto:diane.fleming at gmail.com>> > >>> > >>> From: Anne Gentle <anne at openstack.org > >>> <mailto:anne at openstack.org> <mailto:anne at openstack.org > >>> <mailto:anne at openstack.org>>> > >>> > >>> Date: Wednesday, May 21, 2014 8:48 AM > >>> To: Christian Berendt <berendt at b1-systems.de > >>> <mailto:berendt at b1-systems.de> > >>> <mailto:berendt at b1-systems.de > >>> <mailto:berendt at b1-systems.de>>__> > >>> Cc: "openstack-docs at lists.__openstack.org > >>> <mailto:openstack-docs at lists.openstack.org> > >>> <mailto:openstack-docs at lists.__openstack.org > >>> <mailto:openstack-docs at lists.openstack.org>>" > >>> <Openstack-docs at lists.__openstack.org > >>> <mailto:Openstack-docs at lists.openstack.org> > >>> <mailto:Openstack-docs at lists.__openstack.org > >>> <mailto:Openstack-docs at lists.openstack.org>>> > >>> > >>> Subject: Re: [Openstack-docs] convert the HA guide > >>>from > >>> AsciiDoc to > >>> DocBook > >>> > >>> Glad you brought it up again. Last time someone asked > >>>a > >>> year ago, > >>> here's how it went: > >>> > >>> > >>> > >>>http://lists.openstack.org/__pipermail/openstack-docs/2013-__May/001630 > . > >>>html > >>> > >>> > >>> > >>>< > http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.htm > >>>l> > >>> > >>> > >>> Seems like a recurring theme. Let's see what happens > >>> this time around. > >>> > >>> Anne > >>> > >>> > >>> On Wed, May 21, 2014 at 8:41 AM, Christian Berendt > >>> <berendt at b1-systems.de <mailto:berendt at b1-systems.de> > >>> <mailto:berendt at b1-systems.de > >>> <mailto:berendt at b1-systems.de>>__> wrote: > >>> > >>> Even I like AsciiDoc I would suggest to convert > >>>the > >>> HA guide from > >>> AsciiDoc to DocBook. All other guides are written > >>> in DocBox and > >>> I don't > >>> see any benefit of keeping the HA guide in > >>> AsciiDoc. > >>> > >>> Christian. > >>> > >>> -- > >>> Christian Berendt > >>> Cloud Computing Solution Architect > >>> Mail: berendt at b1-systems.de > >>> <mailto:berendt at b1-systems.de> > >>><mailto:berendt at b1-systems.de > >>> <mailto:berendt at b1-systems.de>> > >>> > >>> > >>> B1 Systems GmbH > >>> Osterfeldstra?e 7 / 85088 Vohburg / > >>> http://www.b1-systems.de > >>> GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: > >>> Ingolstadt,HRB 3537 > >>> > >>> _________________________________________________ > >>> Openstack-docs mailing list > >>> Openstack-docs at lists.__openstack.org > >>> <mailto:Openstack-docs at lists.openstack.org> > >>> <mailto:Openstack-docs at lists.__openstack.org > >>> <mailto:Openstack-docs at lists.openstack.org>> > >>> > >>> > >>> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs > >>> > >>> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> > >>> > >>> > >>> > >>> _________________________________________________ > >>> Openstack-docs mailing list > >>> Openstack-docs at lists.__openstack.org > >>> <mailto:Openstack-docs at lists.openstack.org> > >>> <mailto:Openstack-docs at lists.__openstack.org > >>> <mailto:Openstack-docs at lists.openstack.org>> > >>> > >>> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs > >>> > >>> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> > >>> > >>> > >>> > >>> > >>> _______________________________________________ > >>> Openstack-docs mailing list > >>> Openstack-docs at lists.openstack.org > >>> <mailto:Openstack-docs at lists.openstack.org> > >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > >>> > >>> > >> > >> _______________________________________________ > >> Openstack-docs mailing list > >> Openstack-docs at lists.openstack.org > >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140524/344c833a/attachment-0001.html> From mkassawara at gmail.com Sun May 25 02:36:42 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Sat, 24 May 2014 20:36:42 -0600 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> Message-ID: <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> I'm using a blueprint instead of bugs for the installation guide improvements. I think Anne wants to limit bugs to actual defects/inaccuracies. On Sat, May 24, 2014 at 6:16 PM, Nick Chase <nchase at mirantis.com> wrote: > I'll get started on the structure and the rest of the chapters in the > meantime. > > Question, though: I'd hate to try and put this through as one huge review; > I'm thinking instead maybe one bug for the general changeover, then one bug > each per chapter? I can have everything ready to go to start, and once the > book framework's been merged, we can run the chapter reviews concurrently > to minimize disruption. > > Locally, I've already got the framework in and I'm adding chapters > (keeping in mind that I'll have to re-add Joseph's content when he's > finished). > > Thoughts? > > ---- Nick > > > On Wed, May 21, 2014 at 6:59 PM, Joseph Robinson < > joseph.robinson at rackspace.com> wrote: > >> +1 , One point though - I am working on a patch to the HA guide at the >> moment. I will complete it ASAP so the conversion to XML can start. >> >> My patch: https://review.openstack.org/#/c/93856/2 >> >> -Joseph Robinson >> >> On 22/05/2014 2:25 am, "Emilien Macchi" <emilien.macchi at enovance.com> >> wrote: >> >> >+1 >> > >> >Emilien Macchi >> > >> >On Wed 21 May 2014 06:00:46 PM CEST, Nicholas Chase wrote: >> >> Only if I get to return the favor. :) >> >> >> >> ---- Nick >> >> >> >> On 5/21/2014 11:58 AM, Matt Kassawara wrote: >> >>> Shall we play pin the -1 on the patch? :) >> >>> >> >>> >> >>> On Wed, May 21, 2014 at 9:49 AM, Anne Gentle <anne at openstack.org >> >>> <mailto:anne at openstack.org>> wrote: >> >>> >> >>> Sounds good. If anyone has objections to the conversion, please >> >>> engage in the review. >> >>> Thanks, >> >>> Anne >> >>> >> >>> >> >>> On Wed, May 21, 2014 at 10:41 AM, Nicholas Chase >> >>> <nchase at mirantis.com <mailto:nchase at mirantis.com>> wrote: >> >>> >> >>> Will do! Give me a couple of days and it'll be in and ready >> >>>for >> >>> review. >> >>> >> >>> ---- Nick >> >>> >> >>> >> >>> On 5/21/2014 11:21 AM, Diane Fleming wrote: >> >>> >> >>> Sure Nick, have at it! >> >>> >> >>> /Diane/ >> >>> /-----------------------------__-----------------/ >> >>> >> >>> Diane Fleming >> >>> Software Developer II - US >> >>> diane.fleming at rackspace.com >> >>> <mailto:diane.fleming at rackspace.com> >> >>> Cell 512.323.6799 <tel:512.323.6799> >> >>> Office 512.874.1260 <tel:512.874.1260> >> >>> Skype drfleming0227 >> >>> Google-plus diane.fleming at gmail.com >> >>> <mailto:diane.fleming at gmail.com> >> >>> >> >>> From: Nick Chase <nchase at mirantis.com >> >>> <mailto:nchase at mirantis.com> <mailto:nchase at mirantis.com >> >>> <mailto:nchase at mirantis.com>>> >> >>> >> >>> Date: Wednesday, May 21, 2014 9:22 AM >> >>> To: Diane Fleming <diane.fleming at rackspace.com >> >>> <mailto:diane.fleming at rackspace.com> >> >>> <mailto:diane.fleming at __rackspace.com >> >>> <mailto:diane.fleming at rackspace.com>>> >> >>> Cc: Anne Gentle <anne at openstack.org >> >>> <mailto:anne at openstack.org> <mailto:anne at openstack.org >> >>> <mailto:anne at openstack.org>>>, >> >>> Christian Berendt <berendt at b1-systems.de >> >>> <mailto:berendt at b1-systems.de> >> >>> <mailto:berendt at b1-systems.de >> >>> <mailto:berendt at b1-systems.de>>__>, >> >>> "openstack-docs at lists.__openstack.org >> >>> <mailto:openstack-docs at lists.openstack.org> >> >>> <mailto:openstack-docs at lists.__openstack.org >> >>> <mailto:openstack-docs at lists.openstack.org>>" >> >>> <Openstack-docs at lists.__openstack.org >> >>> <mailto:Openstack-docs at lists.openstack.org> >> >>> <mailto:Openstack-docs at lists.__openstack.org >> >>> <mailto:Openstack-docs at lists.openstack.org>>> >> >>> >> >>> Subject: Re: [Openstack-docs] convert the HA guide from >> >>> AsciiDoc to DocBook >> >>> >> >>> I'd be happy to do the conversion; it's something I'm >> >>> familiar with, I >> >>> have blocks of time where I can do it, and Diane, you can >> >>>be >> >>> more useful >> >>> doing stuff that I can't, as a rule. >> >>> >> >>> That said, if you're set on doing it yourself, I won't >> stop >> >>> you. :) >> >>> >> >>> Let me know. >> >>> >> >>> ---- Nick >> >>> >> >>> >> >>> On Wed, May 21, 2014 at 9:52 AM, Diane Fleming >> >>> <diane.fleming at rackspace.com >> >>> <mailto:diane.fleming at rackspace.com> >> >>> <mailto:diane.fleming at __rackspace.com >> >>> <mailto:diane.fleming at rackspace.com>>> wrote: >> >>> >> >>> Yes please! I'm happy to convert it if everyone >> >>>agrees. >> >>> >> >>> >> >>> /Diane/ >> >>> /-----------------------------__-----------------/ >> >>> >> >>> Diane Fleming >> >>> Software Developer II - US >> >>> diane.fleming at rackspace.com >> >>> <mailto:diane.fleming at rackspace.com> >> >>> <mailto:diane.fleming at __rackspace.com >> >>> <mailto:diane.fleming at rackspace.com>> >> >>> Cell 512.323.6799 <tel:512.323.6799> <tel: >> 512.323.6799 >> >>> <tel:512.323.6799>> >> >>> Office 512.874.1260 <tel:512.874.1260> >> >>> <tel:512.874.1260 <tel:512.874.1260>> >> >>> Skype drfleming0227 >> >>> Google-plus diane.fleming at gmail.com >> >>> <mailto:diane.fleming at gmail.com> >> >>> <mailto:diane.fleming at gmail.__com >> >>> <mailto:diane.fleming at gmail.com>> >> >>> >> >>> From: Anne Gentle <anne at openstack.org >> >>> <mailto:anne at openstack.org> <mailto:anne at openstack.org >> >>> <mailto:anne at openstack.org>>> >> >>> >> >>> Date: Wednesday, May 21, 2014 8:48 AM >> >>> To: Christian Berendt <berendt at b1-systems.de >> >>> <mailto:berendt at b1-systems.de> >> >>> <mailto:berendt at b1-systems.de >> >>> <mailto:berendt at b1-systems.de>>__> >> >>> Cc: "openstack-docs at lists.__openstack.org >> >>> <mailto:openstack-docs at lists.openstack.org> >> >>> <mailto:openstack-docs at lists.__openstack.org >> >>> <mailto:openstack-docs at lists.openstack.org>>" >> >>> <Openstack-docs at lists.__openstack.org >> >>> <mailto:Openstack-docs at lists.openstack.org> >> >>> <mailto:Openstack-docs at lists.__openstack.org >> >>> <mailto:Openstack-docs at lists.openstack.org>>> >> >>> >> >>> Subject: Re: [Openstack-docs] convert the HA guide >> >>>from >> >>> AsciiDoc to >> >>> DocBook >> >>> >> >>> Glad you brought it up again. Last time someone asked >> >>>a >> >>> year ago, >> >>> here's how it went: >> >>> >> >>> >> >>> >> >>> >> http://lists.openstack.org/__pipermail/openstack-docs/2013-__May/001630. >> >>>html >> >>> >> >>> >> >>> >> >>>< >> http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.htm >> >>>l> >> >>> >> >>> >> >>> Seems like a recurring theme. Let's see what happens >> >>> this time around. >> >>> >> >>> Anne >> >>> >> >>> >> >>> On Wed, May 21, 2014 at 8:41 AM, Christian Berendt >> >>> <berendt at b1-systems.de <mailto:berendt at b1-systems.de >> > >> >>> <mailto:berendt at b1-systems.de >> >>> <mailto:berendt at b1-systems.de>>__> wrote: >> >>> >> >>> Even I like AsciiDoc I would suggest to convert >> >>>the >> >>> HA guide from >> >>> AsciiDoc to DocBook. All other guides are written >> >>> in DocBox and >> >>> I don't >> >>> see any benefit of keeping the HA guide in >> >>> AsciiDoc. >> >>> >> >>> Christian. >> >>> >> >>> -- >> >>> Christian Berendt >> >>> Cloud Computing Solution Architect >> >>> Mail: berendt at b1-systems.de >> >>> <mailto:berendt at b1-systems.de> >> >>><mailto:berendt at b1-systems.de >> >>> <mailto:berendt at b1-systems.de>> >> >>> >> >>> >> >>> B1 Systems GmbH >> >>> Osterfeldstra?e 7 / 85088 Vohburg / >> >>> http://www.b1-systems.de >> >>> GF: Ralph Dehner / Unternehmenssitz: Vohburg / >> AG: >> >>> Ingolstadt,HRB 3537 >> >>> >> >>> _________________________________________________ >> >>> Openstack-docs mailing list >> >>> Openstack-docs at lists.__openstack.org >> >>> <mailto:Openstack-docs at lists.openstack.org> >> >>> <mailto:Openstack-docs at lists.__openstack.org >> >>> <mailto:Openstack-docs at lists.openstack.org>> >> >>> >> >>> >> >>> >> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs >> >>> >> >>> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> >> >>> >> >>> >> >>> >> >>> _________________________________________________ >> >>> Openstack-docs mailing list >> >>> Openstack-docs at lists.__openstack.org >> >>> <mailto:Openstack-docs at lists.openstack.org> >> >>> <mailto:Openstack-docs at lists.__openstack.org >> >>> <mailto:Openstack-docs at lists.openstack.org>> >> >>> >> >>> >> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs >> >>> >> >>> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> >> >>> >> >>> >> >>> >> >>> >> >>> _______________________________________________ >> >>> Openstack-docs mailing list >> >>> Openstack-docs at lists.openstack.org >> >>> <mailto:Openstack-docs at lists.openstack.org> >> >>> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >>> >> >>> >> >> >> >> _______________________________________________ >> >> Openstack-docs mailing list >> >> Openstack-docs at lists.openstack.org >> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> > >> >> > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140524/0ba0f678/attachment-0001.html> From nchase at mirantis.com Sun May 25 05:51:39 2014 From: nchase at mirantis.com (Nick Chase) Date: Sun, 25 May 2014 01:51:39 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> Message-ID: <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> Great. Done. https://blueprints.launchpad.net/openstack-manuals/+spec/convert-ha-guide-to-docbook Joseph, do you know when you'll be done with the list fixes? I don't know how to make that numbered list work right in ASCIIDoc, but I do know how to make it work in Docbook, so we could also, if there's agreement here, accept the patch as it is and I'll incorporate it and fix it immediately in the Docbook. ---- Nick On Sat, May 24, 2014 at 10:36 PM, Matt Kassawara <mkassawara at gmail.com>wrote: > I'm using a blueprint instead of bugs for the installation guide > improvements. I think Anne wants to limit bugs to actual > defects/inaccuracies. > > > On Sat, May 24, 2014 at 6:16 PM, Nick Chase <nchase at mirantis.com> wrote: > >> I'll get started on the structure and the rest of the chapters in the >> meantime. >> >> Question, though: I'd hate to try and put this through as one huge >> review; I'm thinking instead maybe one bug for the general changeover, then >> one bug each per chapter? I can have everything ready to go to start, and >> once the book framework's been merged, we can run the chapter reviews >> concurrently to minimize disruption. >> >> Locally, I've already got the framework in and I'm adding chapters >> (keeping in mind that I'll have to re-add Joseph's content when he's >> finished). >> >> Thoughts? >> >> ---- Nick >> >> >> On Wed, May 21, 2014 at 6:59 PM, Joseph Robinson < >> joseph.robinson at rackspace.com> wrote: >> >>> +1 , One point though - I am working on a patch to the HA guide at the >>> moment. I will complete it ASAP so the conversion to XML can start. >>> >>> My patch: https://review.openstack.org/#/c/93856/2 >>> >>> -Joseph Robinson >>> >>> On 22/05/2014 2:25 am, "Emilien Macchi" <emilien.macchi at enovance.com> >>> wrote: >>> >>> >+1 >>> > >>> >Emilien Macchi >>> > >>> >On Wed 21 May 2014 06:00:46 PM CEST, Nicholas Chase wrote: >>> >> Only if I get to return the favor. :) >>> >> >>> >> ---- Nick >>> >> >>> >> On 5/21/2014 11:58 AM, Matt Kassawara wrote: >>> >>> Shall we play pin the -1 on the patch? :) >>> >>> >>> >>> >>> >>> On Wed, May 21, 2014 at 9:49 AM, Anne Gentle <anne at openstack.org >>> >>> <mailto:anne at openstack.org>> wrote: >>> >>> >>> >>> Sounds good. If anyone has objections to the conversion, please >>> >>> engage in the review. >>> >>> Thanks, >>> >>> Anne >>> >>> >>> >>> >>> >>> On Wed, May 21, 2014 at 10:41 AM, Nicholas Chase >>> >>> <nchase at mirantis.com <mailto:nchase at mirantis.com>> wrote: >>> >>> >>> >>> Will do! Give me a couple of days and it'll be in and ready >>> >>>for >>> >>> review. >>> >>> >>> >>> ---- Nick >>> >>> >>> >>> >>> >>> On 5/21/2014 11:21 AM, Diane Fleming wrote: >>> >>> >>> >>> Sure Nick, have at it! >>> >>> >>> >>> /Diane/ >>> >>> /-----------------------------__-----------------/ >>> >>> >>> >>> Diane Fleming >>> >>> Software Developer II - US >>> >>> diane.fleming at rackspace.com >>> >>> <mailto:diane.fleming at rackspace.com> >>> >>> Cell 512.323.6799 <tel:512.323.6799> >>> >>> Office 512.874.1260 <tel:512.874.1260> >>> >>> Skype drfleming0227 >>> >>> Google-plus diane.fleming at gmail.com >>> >>> <mailto:diane.fleming at gmail.com> >>> >>> >>> >>> From: Nick Chase <nchase at mirantis.com >>> >>> <mailto:nchase at mirantis.com> <mailto:nchase at mirantis.com >>> >>> <mailto:nchase at mirantis.com>>> >>> >>> >>> >>> Date: Wednesday, May 21, 2014 9:22 AM >>> >>> To: Diane Fleming <diane.fleming at rackspace.com >>> >>> <mailto:diane.fleming at rackspace.com> >>> >>> <mailto:diane.fleming at __rackspace.com >>> >>> <mailto:diane.fleming at rackspace.com>>> >>> >>> Cc: Anne Gentle <anne at openstack.org >>> >>> <mailto:anne at openstack.org> <mailto:anne at openstack.org >>> >>> <mailto:anne at openstack.org>>>, >>> >>> Christian Berendt <berendt at b1-systems.de >>> >>> <mailto:berendt at b1-systems.de> >>> >>> <mailto:berendt at b1-systems.de >>> >>> <mailto:berendt at b1-systems.de>>__>, >>> >>> "openstack-docs at lists.__openstack.org >>> >>> <mailto:openstack-docs at lists.openstack.org> >>> >>> <mailto:openstack-docs at lists.__openstack.org >>> >>> <mailto:openstack-docs at lists.openstack.org>>" >>> >>> <Openstack-docs at lists.__openstack.org >>> >>> <mailto:Openstack-docs at lists.openstack.org> >>> >>> <mailto:Openstack-docs at lists.__openstack.org >>> >>> <mailto:Openstack-docs at lists.openstack.org>>> >>> >>> >>> >>> Subject: Re: [Openstack-docs] convert the HA guide from >>> >>> AsciiDoc to DocBook >>> >>> >>> >>> I'd be happy to do the conversion; it's something I'm >>> >>> familiar with, I >>> >>> have blocks of time where I can do it, and Diane, you can >>> >>>be >>> >>> more useful >>> >>> doing stuff that I can't, as a rule. >>> >>> >>> >>> That said, if you're set on doing it yourself, I won't >>> stop >>> >>> you. :) >>> >>> >>> >>> Let me know. >>> >>> >>> >>> ---- Nick >>> >>> >>> >>> >>> >>> On Wed, May 21, 2014 at 9:52 AM, Diane Fleming >>> >>> <diane.fleming at rackspace.com >>> >>> <mailto:diane.fleming at rackspace.com> >>> >>> <mailto:diane.fleming at __rackspace.com >>> >>> <mailto:diane.fleming at rackspace.com>>> wrote: >>> >>> >>> >>> Yes please! I'm happy to convert it if everyone >>> >>>agrees. >>> >>> >>> >>> >>> >>> /Diane/ >>> >>> /-----------------------------__-----------------/ >>> >>> >>> >>> Diane Fleming >>> >>> Software Developer II - US >>> >>> diane.fleming at rackspace.com >>> >>> <mailto:diane.fleming at rackspace.com> >>> >>> <mailto:diane.fleming at __rackspace.com >>> >>> <mailto:diane.fleming at rackspace.com>> >>> >>> Cell 512.323.6799 <tel:512.323.6799> <tel: >>> 512.323.6799 >>> >>> <tel:512.323.6799>> >>> >>> Office 512.874.1260 <tel:512.874.1260> >>> >>> <tel:512.874.1260 <tel:512.874.1260>> >>> >>> Skype drfleming0227 >>> >>> Google-plus diane.fleming at gmail.com >>> >>> <mailto:diane.fleming at gmail.com> >>> >>> <mailto:diane.fleming at gmail.__com >>> >>> <mailto:diane.fleming at gmail.com>> >>> >>> >>> >>> From: Anne Gentle <anne at openstack.org >>> >>> <mailto:anne at openstack.org> <mailto:anne at openstack.org >>> >>> <mailto:anne at openstack.org>>> >>> >>> >>> >>> Date: Wednesday, May 21, 2014 8:48 AM >>> >>> To: Christian Berendt <berendt at b1-systems.de >>> >>> <mailto:berendt at b1-systems.de> >>> >>> <mailto:berendt at b1-systems.de >>> >>> <mailto:berendt at b1-systems.de>>__> >>> >>> Cc: "openstack-docs at lists.__openstack.org >>> >>> <mailto:openstack-docs at lists.openstack.org> >>> >>> <mailto:openstack-docs at lists.__openstack.org >>> >>> <mailto:openstack-docs at lists.openstack.org>>" >>> >>> <Openstack-docs at lists.__openstack.org >>> >>> <mailto:Openstack-docs at lists.openstack.org> >>> >>> <mailto:Openstack-docs at lists.__openstack.org >>> >>> <mailto:Openstack-docs at lists.openstack.org>>> >>> >>> >>> >>> Subject: Re: [Openstack-docs] convert the HA guide >>> >>>from >>> >>> AsciiDoc to >>> >>> DocBook >>> >>> >>> >>> Glad you brought it up again. Last time someone >>> asked >>> >>>a >>> >>> year ago, >>> >>> here's how it went: >>> >>> >>> >>> >>> >>> >>> >>> >>> http://lists.openstack.org/__pipermail/openstack-docs/2013-__May/001630. >>> >>>html >>> >>> >>> >>> >>> >>> >>> >>>< >>> http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.htm >>> >>>l> >>> >>> >>> >>> >>> >>> Seems like a recurring theme. Let's see what happens >>> >>> this time around. >>> >>> >>> >>> Anne >>> >>> >>> >>> >>> >>> On Wed, May 21, 2014 at 8:41 AM, Christian Berendt >>> >>> <berendt at b1-systems.de <mailto: >>> berendt at b1-systems.de> >>> >>> <mailto:berendt at b1-systems.de >>> >>> <mailto:berendt at b1-systems.de>>__> wrote: >>> >>> >>> >>> Even I like AsciiDoc I would suggest to convert >>> >>>the >>> >>> HA guide from >>> >>> AsciiDoc to DocBook. All other guides are >>> written >>> >>> in DocBox and >>> >>> I don't >>> >>> see any benefit of keeping the HA guide in >>> >>> AsciiDoc. >>> >>> >>> >>> Christian. >>> >>> >>> >>> -- >>> >>> Christian Berendt >>> >>> Cloud Computing Solution Architect >>> >>> Mail: berendt at b1-systems.de >>> >>> <mailto:berendt at b1-systems.de> >>> >>><mailto:berendt at b1-systems.de >>> >>> <mailto:berendt at b1-systems.de>> >>> >>> >>> >>> >>> >>> B1 Systems GmbH >>> >>> Osterfeldstra?e 7 / 85088 Vohburg / >>> >>> http://www.b1-systems.de >>> >>> GF: Ralph Dehner / Unternehmenssitz: Vohburg / >>> AG: >>> >>> Ingolstadt,HRB 3537 >>> >>> >>> >>> >>> _________________________________________________ >>> >>> Openstack-docs mailing list >>> >>> Openstack-docs at lists.__openstack.org >>> >>> <mailto:Openstack-docs at lists.openstack.org> >>> >>> <mailto:Openstack-docs at lists.__openstack.org >>> >>> <mailto:Openstack-docs at lists.openstack.org>> >>> >>> >>> >>> >>> >>> >>> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs >>> >>> >>> >>> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> >>> >>> >>> >>> >>> >>> >>> >>> _________________________________________________ >>> >>> Openstack-docs mailing list >>> >>> Openstack-docs at lists.__openstack.org >>> >>> <mailto:Openstack-docs at lists.openstack.org> >>> >>> <mailto:Openstack-docs at lists.__openstack.org >>> >>> <mailto:Openstack-docs at lists.openstack.org>> >>> >>> >>> >>> >>> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs >>> >>> >>> >>> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> _______________________________________________ >>> >>> Openstack-docs mailing list >>> >>> Openstack-docs at lists.openstack.org >>> >>> <mailto:Openstack-docs at lists.openstack.org> >>> >>> >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>> >>> >>> >>> >>> >> >>> >> _______________________________________________ >>> >> Openstack-docs mailing list >>> >> Openstack-docs at lists.openstack.org >>> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>> > >>> >>> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140525/f44f29f1/attachment-0001.html> From mkassawara at gmail.com Sun May 25 16:09:06 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Sun, 25 May 2014 10:09:06 -0600 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CABA+jQpmcQskEtNC7K2+FO0ubY-VqAHC=e6L-R-bSpVtQyEkWg@mail.gmail.com> References: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> <1168D4D0-7E00-4496-A6DA-BC1F409C6468@RACKSPACE.COM> <CABA+jQozp30xFbAMU24abS9J5MVWBK3Crm62qTedAhAOFVXFiw@mail.gmail.com> <8AA6205D-A359-4827-81D0-2993E00700F5@RACKSPACE.COM> <CABA+jQpmcQskEtNC7K2+FO0ubY-VqAHC=e6L-R-bSpVtQyEkWg@mail.gmail.com> Message-ID: <CABA+jQrg_YwCcP5DS4yhuozFn-G_Za0LeNTjZACeqS6B++65Dw@mail.gmail.com> Whoops, I noticed this discussion went off-list. On Sat, May 24, 2014 at 8:44 PM, Matt Kassawara <mkassawara at gmail.com>wrote: > I can't find any requirements for IDs outside of sections. For > consistency, I think we should require IDs on figures and tables too. > > P.S. - I just noticed that our thread went off-list. Should I put it back? > > > On Sat, May 24, 2014 at 7:47 PM, Diane Fleming < > diane.fleming at rackspace.com> wrote: > >> Yes, sections are not named consistently. Are id's required on figures >> and tables? Or only if you cross-ref them? (I don't remember.) >> >> Sent from my iPhone >> >> On May 24, 2014, at 11:15 AM, "Matt Kassawara" <mkassawara at gmail.com> >> wrote: >> >> Thanks! I took a look and mostly found consistency with bk_* and ch_*, >> but sections often lack section_*. Many figures and tables often lack IDs. >> >> >> On Sat, May 24, 2014 at 9:33 AM, Diane Fleming < >> diane.fleming at rackspace.com> wrote: >> >>> Matt, look at openstack-manuals -> user-guide, config ref, common, or >>> the admin guide - i think all those use a consistent naming style. Chapters >>> ch_*, sections section_*, books bk_*. I do not remember what we used for >>> images and tables - but look there for existing conventions. >>> >>> Sent from my iPhone >>> >>> On May 24, 2014, at 9:46 AM, "Matt Kassawara" <mkassawara at gmail.com> >>> wrote: >>> >>> Would consistently indicating type within an ID help clarify >>> references? For example, chapter IDs always start with "ch_", section IDs >>> always start with "sec_", figure IDs start with "fig_", etc. >>> >>> >>> On Thu, May 22, 2014 at 5:58 PM, Matt Kassawara <mkassawara at gmail.com>wrote: >>> >>>> I found some inconsistencies with filenames and chapter/section IDs >>>> while auditing the Installation Guide. I thought I found some conventions >>>> while updating the guide for Icehouse, but can't find them now. If they >>>> exist, can someone point me to them? If not, we should develop some so we >>>> can proceed with the improvements. >>>> >>> >>> _______________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.openstack.org >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>> >>> >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140525/7ec61349/attachment.html> From aj at suse.com Sun May 25 19:50:27 2014 From: aj at suse.com (Andreas Jaeger) Date: Sun, 25 May 2014 21:50:27 +0200 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> References: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> Message-ID: <53824983.3060301@suse.com> On 05/24/2014 04:45 PM, Matt Kassawara wrote: > Would consistently indicating type within an ID help clarify references? > For example, chapter IDs always start with "ch_", section IDs always > start with "sec_", figure IDs start with "fig_", etc. Yeah, that would help. When I add xml:ids, I normally use sec_FILENAME for the first section and sec_FILENAME_TITLE for any additional sections. FILENAME is either the filename or the first title. I don't think we should remain now everything - but we should have a rule for new files and new xml:ids moving forward. Remaining has the problem that it creates new URLs and the old ones stay. Once that issue is fixed, we can rename more easily, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Sun May 25 19:55:17 2014 From: aj at suse.com (Andreas Jaeger) Date: Sun, 25 May 2014 21:55:17 +0200 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> Message-ID: <53824AA5.8020702@suse.com> On 05/25/2014 07:51 AM, Nick Chase wrote: > Great. Done. > https://blueprints.launchpad.net/openstack-manuals/+spec/convert-ha-guide-to-docbook > > Joseph, do you know when you'll be done with the list fixes? I don't > know how to make that numbered list work right in ASCIIDoc, but I do > know how to make it work in Docbook, so we could also, if there's > agreement here, accept the patch as it is and I'll incorporate it and > fix it immediately in the Docbook. I'm fine with accepting the patch if you get this done quickly. Feel free to ignore my -1 - but I'm not removing it to give others the chance to chime in, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From nchase at mirantis.com Sun May 25 20:05:43 2014 From: nchase at mirantis.com (Nick Chase) Date: Sun, 25 May 2014 16:05:43 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <53824AA5.8020702@suse.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> <53824AA5.8020702@suse.com> Message-ID: <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> I can do it immediately. I was planning to work on this this afternoon so that would be perfect. ---- Nick On May 25, 2014 3:55 PM, "Andreas Jaeger" <aj at suse.com> wrote: > On 05/25/2014 07:51 AM, Nick Chase wrote: > > Great. Done. > > > https://blueprints.launchpad.net/openstack-manuals/+spec/convert-ha-guide-to-docbook > > > > Joseph, do you know when you'll be done with the list fixes? I don't > > know how to make that numbered list work right in ASCIIDoc, but I do > > know how to make it work in Docbook, so we could also, if there's > > agreement here, accept the patch as it is and I'll incorporate it and > > fix it immediately in the Docbook. > > I'm fine with accepting the patch if you get this done quickly. Feel > free to ignore my -1 - but I'm not removing it to give others the chance > to chime in, > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140525/406c97ba/attachment.html> From anne at openstack.org Sun May 25 21:32:25 2014 From: anne at openstack.org (Anne Gentle) Date: Sun, 25 May 2014 16:32:25 -0500 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <53824983.3060301@suse.com> References: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> <53824983.3060301@suse.com> Message-ID: <CAD0KtVFPYs7LdCYUunnD5Yk1qvoCAcoUvjgkVDbW2YyuNSU0Xg@mail.gmail.com> Something to think about for ch and sec is that we won't always author in a book-like manner, so let's not lock ourselves into that sort of thinking due to current file names. Stick to the install guide for now, to apply conventions, just please don't use something as meaningful semantically as chapter and section. Anne On Sun, May 25, 2014 at 2:50 PM, Andreas Jaeger <aj at suse.com> wrote: > On 05/24/2014 04:45 PM, Matt Kassawara wrote: > > Would consistently indicating type within an ID help clarify references? > > For example, chapter IDs always start with "ch_", section IDs always > > start with "sec_", figure IDs start with "fig_", etc. > > > Yeah, that would help. > > When I add xml:ids, I normally use sec_FILENAME for the first section > and sec_FILENAME_TITLE for any additional sections. FILENAME is either > the filename or the first title. > > I don't think we should remain now everything - but we should have a > rule for new files and new xml:ids moving forward. Remaining has the > problem that it creates new URLs and the old ones stay. Once that issue > is fixed, we can rename more easily, > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140525/88666b3d/attachment.html> From sgordon at redhat.com Sun May 25 21:50:41 2014 From: sgordon at redhat.com (Steve Gordon) Date: Sun, 25 May 2014 17:50:41 -0400 (EDT) Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CAD0KtVFPYs7LdCYUunnD5Yk1qvoCAcoUvjgkVDbW2YyuNSU0Xg@mail.gmail.com> References: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> <53824983.3060301@suse.com> <CAD0KtVFPYs7LdCYUunnD5Yk1qvoCAcoUvjgkVDbW2YyuNSU0Xg@mail.gmail.com> Message-ID: <1965553805.18459527.1401054641947.JavaMail.zimbra@redhat.com> ----- Original Message ----- > From: "Anne Gentle" <anne at openstack.org> > To: "Andreas Jaeger" <aj at suse.com> > > Something to think about for ch and sec is that we won't always author in a > book-like manner, so let's not lock ourselves into that sort of thinking > due to current file names. > > Stick to the install guide for now, to apply conventions, just please don't > use something as meaningful semantically as chapter and section. I actually think it's important/useful information in the filename. It reflects the root node of the file's XML which has an impact on where you can nest/include it in another document (you can't include a chapter in a section for example, but you can include a section in a chapter). It's got more to do with the realities of the format being used than whether we're thinking in terms of books, articles, etc. Granted if we moved to a non-XML format this would no longer be the case, but I think we'd have bigger conversion issues than bulk renaming the files/links. ;) -Steve From anne at openstack.org Sun May 25 23:27:26 2014 From: anne at openstack.org (Anne Gentle) Date: Sun, 25 May 2014 18:27:26 -0500 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <1965553805.18459527.1401054641947.JavaMail.zimbra@redhat.com> References: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> <53824983.3060301@suse.com> <CAD0KtVFPYs7LdCYUunnD5Yk1qvoCAcoUvjgkVDbW2YyuNSU0Xg@mail.gmail.com> <1965553805.18459527.1401054641947.JavaMail.zimbra@redhat.com> Message-ID: <CAD0KtVEGJ0jrFCMFh5nXOBee6ZbRCeE90GeLmXZ_8XZRGj9Qpw@mail.gmail.com> On Sun, May 25, 2014 at 4:50 PM, Steve Gordon <sgordon at redhat.com> wrote: > ----- Original Message ----- > > From: "Anne Gentle" <anne at openstack.org> > > To: "Andreas Jaeger" <aj at suse.com> > > > > Something to think about for ch and sec is that we won't always author > in a > > book-like manner, so let's not lock ourselves into that sort of thinking > > due to current file names. > > > > Stick to the install guide for now, to apply conventions, just please > don't > > use something as meaningful semantically as chapter and section. > > I actually think it's important/useful information in the filename. It > reflects the root node of the file's XML which has an impact on where you > can nest/include it in another document (you can't include a chapter in a > section for example, but you can include a section in a chapter). It's got > more to do with the realities of the format being used than whether we're > thinking in terms of books, articles, etc. > I agree it's a useful codification in the file name, but I don't think we want it in the xml:id. The xml:id is used for SEO, for human-readable URLs, and so on. Let's not leak our abstraction further than we have to. :) Anne > > Granted if we moved to a non-XML format this would no longer be the case, > but I think we'd have bigger conversion issues than bulk renaming the > files/links. ;) > > -Steve > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140525/0ccc83f4/attachment.html> From joseph.robinson at RACKSPACE.COM Sun May 25 23:47:35 2014 From: joseph.robinson at RACKSPACE.COM (Joseph Robinson) Date: Sun, 25 May 2014 23:47:35 +0000 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> <53824AA5.8020702@suse.com> <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> Message-ID: <CFA8BF47.13C7%joseph.robinson@rackspace.com> Yes, that?s a great idea, and I agree. Apologies for the delay. It will be great to have the procedure built with xml. It will take more time to find out why it is not building the procedure correctly in Ascii then it would to merge the changes and immediately rebuild with xml. Proceed when ready. -Joe From: Nick Chase <nchase at mirantis.com<mailto:nchase at mirantis.com>> Date: Monday, 26 May 2014 6:05 am To: aj <aj at suse.com<mailto:aj at suse.com>> Cc: "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>> Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook I can do it immediately. I was planning to work on this this afternoon so that would be perfect. ---- Nick On May 25, 2014 3:55 PM, "Andreas Jaeger" <aj at suse.com<mailto:aj at suse.com>> wrote: On 05/25/2014 07:51 AM, Nick Chase wrote: > Great. Done. > https://blueprints.launchpad.net/openstack-manuals/+spec/convert-ha-guide-to-docbook > > Joseph, do you know when you'll be done with the list fixes? I don't > know how to make that numbered list work right in ASCIIDoc, but I do > know how to make it work in Docbook, so we could also, if there's > agreement here, accept the patch as it is and I'll incorporate it and > fix it immediately in the Docbook. I'm fine with accepting the patch if you get this done quickly. Feel free to ignore my -1 - but I'm not removing it to give others the chance to chime in, Andreas -- Andreas Jaeger aj@{suse.com<http://suse.com>,opensuse.org<http://opensuse.org>} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140525/80144c06/attachment.html> From diane.fleming at RACKSPACE.COM Sun May 25 23:59:00 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Sun, 25 May 2014 23:59:00 +0000 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CAD0KtVEGJ0jrFCMFh5nXOBee6ZbRCeE90GeLmXZ_8XZRGj9Qpw@mail.gmail.com> References: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> <53824983.3060301@suse.com> <CAD0KtVFPYs7LdCYUunnD5Yk1qvoCAcoUvjgkVDbW2YyuNSU0Xg@mail.gmail.com> <1965553805.18459527.1401054641947.JavaMail.zimbra@redhat.com>, <CAD0KtVEGJ0jrFCMFh5nXOBee6ZbRCeE90GeLmXZ_8XZRGj9Qpw@mail.gmail.com> Message-ID: <35069176-7827-4378-AB54-C252732D58EB@RACKSPACE.COM> +1 for file name conventions -1 for xml:id conventions Sent from my iPhone On May 25, 2014, at 6:28 PM, "Anne Gentle" <anne at openstack.org<mailto:anne at openstack.org>> wrote: On Sun, May 25, 2014 at 4:50 PM, Steve Gordon <sgordon at redhat.com<mailto:sgordon at redhat.com>> wrote: ----- Original Message ----- > From: "Anne Gentle" <anne at openstack.org<mailto:anne at openstack.org>> > To: "Andreas Jaeger" <aj at suse.com<mailto:aj at suse.com>> > > Something to think about for ch and sec is that we won't always author in a > book-like manner, so let's not lock ourselves into that sort of thinking > due to current file names. > > Stick to the install guide for now, to apply conventions, just please don't > use something as meaningful semantically as chapter and section. I actually think it's important/useful information in the filename. It reflects the root node of the file's XML which has an impact on where you can nest/include it in another document (you can't include a chapter in a section for example, but you can include a section in a chapter). It's got more to do with the realities of the format being used than whether we're thinking in terms of books, articles, etc. I agree it's a useful codification in the file name, but I don't think we want it in the xml:id. The xml:id is used for SEO, for human-readable URLs, and so on. Let's not leak our abstraction further than we have to. :) Anne Granted if we moved to a non-XML format this would no longer be the case, but I think we'd have bigger conversion issues than bulk renaming the files/links. ;) -Steve _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140525/32c8f332/attachment.html> From nchase at mirantis.com Mon May 26 05:44:20 2014 From: nchase at mirantis.com (Nick Chase) Date: Mon, 26 May 2014 01:44:20 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CFA8BF47.13C7%joseph.robinson@rackspace.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> <53824AA5.8020702@suse.com> <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> <CFA8BF47.13C7%joseph.robinson@rackspace.com> Message-ID: <CA+p99Gn3cBBKW1cXX1seXuoUfd7Ahn9vNLw=nL734T_kABwmpA@mail.gmail.com> OK, so here's where we are: I've got one patch in that does the wholesale conversion to XML, but doesn't have things broken down and audited yet. That's here: https://review.openstack.org/#/c/95401/ However, as you can see, it doesn't pass tox. It doesn't pass tox locally because it's trying to convert it to docbook, and there's nothing to convert. I've removed that functionality from os-docs-tools here: https://review.openstack.org/#/c/95406/ But that needs to be merged before I can run tox on the book to look for other problems. I think. Anyway, I've just commented code here; I'm happy to actually delete it if I've done the right thing, but I didn't want to just hack out a bunch of code without someone more familiar looking at it first. Thanks! ---- Nick On Sun, May 25, 2014 at 7:47 PM, Joseph Robinson < joseph.robinson at rackspace.com> wrote: > Yes, that?s a great idea, and I agree. Apologies for the delay. It will > be great to have the procedure built with xml. > > It will take more time to find out why it is not building the procedure > correctly in Ascii then it would to merge the changes and immediately > rebuild with xml. > > Proceed when ready. > > -Joe > > From: Nick Chase <nchase at mirantis.com> > Date: Monday, 26 May 2014 6:05 am > To: aj <aj at suse.com> > Cc: "openstack-docs at lists.openstack.org" < > openstack-docs at lists.openstack.org> > > Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to > DocBook > > I can do it immediately. I was planning to work on this this afternoon > so that would be perfect. > > ---- Nick > On May 25, 2014 3:55 PM, "Andreas Jaeger" <aj at suse.com> wrote: > >> On 05/25/2014 07:51 AM, Nick Chase wrote: >> > Great. Done. >> > >> https://blueprints.launchpad.net/openstack-manuals/+spec/convert-ha-guide-to-docbook >> > >> > Joseph, do you know when you'll be done with the list fixes? I don't >> > know how to make that numbered list work right in ASCIIDoc, but I do >> > know how to make it work in Docbook, so we could also, if there's >> > agreement here, accept the patch as it is and I'll incorporate it and >> > fix it immediately in the Docbook. >> >> I'm fine with accepting the patch if you get this done quickly. Feel >> free to ignore my -1 - but I'm not removing it to give others the chance >> to chime in, >> >> Andreas >> -- >> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany >> GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/8e486515/attachment-0001.html> From aj at suse.com Mon May 26 06:24:04 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 26 May 2014 08:24:04 +0200 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> <53824AA5.8020702@suse.com> <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> Message-ID: <5382DE04.70900@suse.com> Thanks Nick for the conversion! So, to get this in, we need to do the following: 1) We need a new release of openstack-doc-tools with this patch in: https://review.openstack.org/#/c/95406/ 2) Approve Nick's patch https://review.openstack.org/#/c/95401/ 3) Update infra-job (I'll ping them once 2 is in): https://review.openstack.org/#/c/95414/ Reviews of patches are welcome, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Mon May 26 06:25:53 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 26 May 2014 08:25:53 +0200 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CA+p99Gn3cBBKW1cXX1seXuoUfd7Ahn9vNLw=nL734T_kABwmpA@mail.gmail.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> <53824AA5.8020702@suse.com> <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> <CFA8BF47.13C7%joseph.robinson@rackspace.com> <CA+p99Gn3cBBKW1cXX1seXuoUfd7Ahn9vNLw=nL734T_kABwmpA@mail.gmail.com> Message-ID: <5382DE71.2080908@suse.com> On 05/26/2014 07:44 AM, Nick Chase wrote: > OK, so here's where we are: > > I've got one patch in that does the wholesale conversion to XML, but > doesn't have things broken down and audited yet. That's here: > > https://review.openstack.org/#/c/95401/ > > However, as you can see, it doesn't pass tox. It doesn't pass tox > locally because it's trying to convert it to docbook, and there's > nothing to convert. I've removed that functionality from os-docs-tools > here: > > https://review.openstack.org/#/c/95406/ > > But that needs to be merged before I can run tox on the book to look for > other problems. I think. Agreed. I should have read my whole INBOX before patching and answering ;) > Anyway, I've just commented code here; I'm happy to actually delete it > if I've done the right thing, but I didn't want to just hack out a bunch > of code without someone more familiar looking at it first. You commented out too much in that file and missed the parts that actually builds the books, I've updated your patch. Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From joseph.robinson at RACKSPACE.COM Mon May 26 07:41:49 2014 From: joseph.robinson at RACKSPACE.COM (Joseph Robinson) Date: Mon, 26 May 2014 07:41:49 +0000 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <5382DE71.2080908@suse.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> <53824AA5.8020702@suse.com> <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> <CFA8BF47.13C7%joseph.robinson@rackspace.com> <CA+p99Gn3cBBKW1cXX1seXuoUfd7Ahn9vNLw=nL734T_kABwmpA@mail.gmail.com> <5382DE71.2080908@suse.com> Message-ID: <CFA92DCF.13E2%joseph.robinson@rackspace.com> I rewrote the edits to the HA guide with explicit instead of implicit numbering, and sorry it took so long to research and apply this AsciiDoc list type. The patch is ready to go for the conversion now. ?Joe On 26/05/2014 4:25 pm, "Andreas Jaeger" <aj at suse.com> wrote: >On 05/26/2014 07:44 AM, Nick Chase wrote: >> OK, so here's where we are: >> >> I've got one patch in that does the wholesale conversion to XML, but >> doesn't have things broken down and audited yet. That's here: >> >> https://review.openstack.org/#/c/95401/ >> >> However, as you can see, it doesn't pass tox. It doesn't pass tox >> locally because it's trying to convert it to docbook, and there's >> nothing to convert. I've removed that functionality from os-docs-tools >> here: >> >> https://review.openstack.org/#/c/95406/ >> >> But that needs to be merged before I can run tox on the book to look for >> other problems. I think. > >Agreed. I should have read my whole INBOX before patching and answering ;) > >> Anyway, I've just commented code here; I'm happy to actually delete it >> if I've done the right thing, but I didn't want to just hack out a bunch >> of code without someone more familiar looking at it first. > >You commented out too much in that file and missed the parts that >actually builds the books, I've updated your patch. > >Andreas >-- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From nchase at mirantis.com Mon May 26 14:32:23 2014 From: nchase at mirantis.com (Nick Chase) Date: Mon, 26 May 2014 10:32:23 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CFA92DCF.13E2%joseph.robinson@rackspace.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> <53824AA5.8020702@suse.com> <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> <CFA8BF47.13C7%joseph.robinson@rackspace.com> <CA+p99Gn3cBBKW1cXX1seXuoUfd7Ahn9vNLw=nL734T_kABwmpA@mail.gmail.com> <5382DE71.2080908@suse.com> <CFA92DCF.13E2%joseph.robinson@rackspace.com> Message-ID: <CA+p99Gn5KUSeinY8nR-=hc=6NPBqtqYjHu=3Lvbk00dXJwtA1A@mail.gmail.com> I actually fixed it in the XML version so it's ok. On May 26, 2014 3:41 AM, "Joseph Robinson" <joseph.robinson at rackspace.com> wrote: > I rewrote the edits to the HA guide with explicit instead of implicit > numbering, and sorry it took so long to research and apply this AsciiDoc > list type. The patch is ready to go for the conversion now. > > ?Joe > > On 26/05/2014 4:25 pm, "Andreas Jaeger" <aj at suse.com> wrote: > > >On 05/26/2014 07:44 AM, Nick Chase wrote: > >> OK, so here's where we are: > >> > >> I've got one patch in that does the wholesale conversion to XML, but > >> doesn't have things broken down and audited yet. That's here: > >> > >> https://review.openstack.org/#/c/95401/ > >> > >> However, as you can see, it doesn't pass tox. It doesn't pass tox > >> locally because it's trying to convert it to docbook, and there's > >> nothing to convert. I've removed that functionality from os-docs-tools > >> here: > >> > >> https://review.openstack.org/#/c/95406/ > >> > >> But that needs to be merged before I can run tox on the book to look for > >> other problems. I think. > > > >Agreed. I should have read my whole INBOX before patching and answering ;) > > > >> Anyway, I've just commented code here; I'm happy to actually delete it > >> if I've done the right thing, but I didn't want to just hack out a bunch > >> of code without someone more familiar looking at it first. > > > >You commented out too much in that file and missed the parts that > >actually builds the books, I've updated your patch. > > > >Andreas > >-- > > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/42889aed/attachment.html> From nchase at mirantis.com Mon May 26 14:35:43 2014 From: nchase at mirantis.com (Nick Chase) Date: Mon, 26 May 2014 10:35:43 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CA+p99Gn5KUSeinY8nR-=hc=6NPBqtqYjHu=3Lvbk00dXJwtA1A@mail.gmail.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> <53824AA5.8020702@suse.com> <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> <CFA8BF47.13C7%joseph.robinson@rackspace.com> <CA+p99Gn3cBBKW1cXX1seXuoUfd7Ahn9vNLw=nL734T_kABwmpA@mail.gmail.com> <5382DE71.2080908@suse.com> <CFA92DCF.13E2%joseph.robinson@rackspace.com> <CA+p99Gn5KUSeinY8nR-=hc=6NPBqtqYjHu=3Lvbk00dXJwtA1A@mail.gmail.com> Message-ID: <CA+p99GkvhLf3VBrXT_2h=2R6rgLt+jced2zTec-aGFwb0tC2OQ@mail.gmail.com> I should be clear. Before I did the conversion, I applied your patch. I then did the conversion and fixed the list so that it renders properly. ---- Nick On May 26, 2014 10:32 AM, "Nick Chase" <nchase at mirantis.com> wrote: > I actually fixed it in the XML version so it's ok. > On May 26, 2014 3:41 AM, "Joseph Robinson" <joseph.robinson at rackspace.com> > wrote: > >> I rewrote the edits to the HA guide with explicit instead of implicit >> numbering, and sorry it took so long to research and apply this AsciiDoc >> list type. The patch is ready to go for the conversion now. >> >> ?Joe >> >> On 26/05/2014 4:25 pm, "Andreas Jaeger" <aj at suse.com> wrote: >> >> >On 05/26/2014 07:44 AM, Nick Chase wrote: >> >> OK, so here's where we are: >> >> >> >> I've got one patch in that does the wholesale conversion to XML, but >> >> doesn't have things broken down and audited yet. That's here: >> >> >> >> https://review.openstack.org/#/c/95401/ >> >> >> >> However, as you can see, it doesn't pass tox. It doesn't pass tox >> >> locally because it's trying to convert it to docbook, and there's >> >> nothing to convert. I've removed that functionality from os-docs-tools >> >> here: >> >> >> >> https://review.openstack.org/#/c/95406/ >> >> >> >> But that needs to be merged before I can run tox on the book to look >> for >> >> other problems. I think. >> > >> >Agreed. I should have read my whole INBOX before patching and answering >> ;) >> > >> >> Anyway, I've just commented code here; I'm happy to actually delete it >> >> if I've done the right thing, but I didn't want to just hack out a >> bunch >> >> of code without someone more familiar looking at it first. >> > >> >You commented out too much in that file and missed the parts that >> >actually builds the books, I've updated your patch. >> > >> >Andreas >> >-- >> > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi >> > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany >> > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) >> > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 >> >> -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/486310d5/attachment.html> From nchase at mirantis.com Mon May 26 14:39:39 2014 From: nchase at mirantis.com (Nick Chase) Date: Mon, 26 May 2014 10:39:39 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <5382DE71.2080908@suse.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> <53824AA5.8020702@suse.com> <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> <CFA8BF47.13C7%joseph.robinson@rackspace.com> <CA+p99Gn3cBBKW1cXX1seXuoUfd7Ahn9vNLw=nL734T_kABwmpA@mail.gmail.com> <5382DE71.2080908@suse.com> Message-ID: <CA+p99GnrsU07jj7j+=bb7B0=k8_rPDnN2fQmNdN_WDC=D14jhg@mail.gmail.com> On May 26, 2014 2:25 AM, "Andreas Jaeger" <aj at suse.com> wrote: > > On 05/26/2014 07:44 AM, Nick Chase wrote: > > OK, so here's where we are: > > > > I've got one patch in that does the wholesale conversion to XML, but > > doesn't have things broken down and audited yet. That's here: > > > > https://review.openstack.org/#/c/95401/ > > > > However, as you can see, it doesn't pass tox. It doesn't pass tox > > locally because it's trying to convert it to docbook, and there's > > nothing to convert. I've removed that functionality from os-docs-tools > > here: > > > > https://review.openstack.org/#/c/95406/ > > > > But that needs to be merged before I can run tox on the book to look for > > other problems. I think. > > Agreed. I should have read my whole INBOX before patching and answering ;) If you're like me you'd never get anything done that way. :) > > Anyway, I've just commented code here; I'm happy to actually delete it > > if I've done the right thing, but I didn't want to just hack out a bunch > > of code without someone more familiar looking at it first. > > You commented out too much in that file and missed the parts that > actually builds the books, I've updated your patch. And that's why I commented instead of deleting. :) Thanks for the assist. Anyway I've got the next one, which breaks it all down to the section level, just about ready to go. Then i can do cleanup. ---- Nick -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/c88e2929/attachment.html> From mkassawara at gmail.com Mon May 26 14:42:53 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Mon, 26 May 2014 08:42:53 -0600 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <35069176-7827-4378-AB54-C252732D58EB@RACKSPACE.COM> References: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> <53824983.3060301@suse.com> <CAD0KtVFPYs7LdCYUunnD5Yk1qvoCAcoUvjgkVDbW2YyuNSU0Xg@mail.gmail.com> <1965553805.18459527.1401054641947.JavaMail.zimbra@redhat.com> <CAD0KtVEGJ0jrFCMFh5nXOBee6ZbRCeE90GeLmXZ_8XZRGj9Qpw@mail.gmail.com> <35069176-7827-4378-AB54-C252732D58EB@RACKSPACE.COM> Message-ID: <CABA+jQoKAoy8OUtNNf1bwUK3jCRrYqGRx22NpH_eUuATgD0fig@mail.gmail.com> How about describing the hierarchy in IDs, but not necessarily with ch_, section_, etc? For example: ch_networking -> networking section_neutron-networking-ml2 -> networking-neutron-ml2 section_neutron-ml2-controller-node -> networking-neutron-ml2-controller-node Also, would it help to indicate type in figure, table, and similar element IDs? For example: example-architecture-with-legacy-networking -> fig_example-architecture-with-legacy-networking table1 -> tab_getstart-openstack-services (from common/ch_getstart.xml) para3 -> par_getstart-3 (from common/ch_getstart.xml) Or... am I still the totally crazy noob? P.S. - I'm also interested in ideas for standardizing filenames and/or locations for figures. On Sun, May 25, 2014 at 5:59 PM, Diane Fleming <diane.fleming at rackspace.com>wrote: > +1 for file name conventions > -1 for xml:id conventions > > > > Sent from my iPhone > > On May 25, 2014, at 6:28 PM, "Anne Gentle" <anne at openstack.org> wrote: > > > > > On Sun, May 25, 2014 at 4:50 PM, Steve Gordon <sgordon at redhat.com> wrote: > >> ----- Original Message ----- >> > From: "Anne Gentle" <anne at openstack.org> >> > To: "Andreas Jaeger" <aj at suse.com> >> > >> > Something to think about for ch and sec is that we won't always author >> in a >> > book-like manner, so let's not lock ourselves into that sort of thinking >> > due to current file names. >> > >> > Stick to the install guide for now, to apply conventions, just please >> don't >> > use something as meaningful semantically as chapter and section. >> >> I actually think it's important/useful information in the filename. It >> reflects the root node of the file's XML which has an impact on where you >> can nest/include it in another document (you can't include a chapter in a >> section for example, but you can include a section in a chapter). It's got >> more to do with the realities of the format being used than whether we're >> thinking in terms of books, articles, etc. >> > > I agree it's a useful codification in the file name, but I don't think > we want it in the xml:id. The xml:id is used for SEO, for human-readable > URLs, and so on. Let's not leak our abstraction further than we have to. :) > Anne > > >> >> Granted if we moved to a non-XML format this would no longer be the case, >> but I think we'd have bigger conversion issues than bulk renaming the >> files/links. ;) >> >> -Steve >> > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/72fc62dd/attachment-0001.html> From diane.fleming at RACKSPACE.COM Mon May 26 14:47:42 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Mon, 26 May 2014 14:47:42 +0000 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CABA+jQoKAoy8OUtNNf1bwUK3jCRrYqGRx22NpH_eUuATgD0fig@mail.gmail.com> Message-ID: <CFA8BDF2.2DFA0%diane.fleming@rackspace.com> Matt, What problem are you trying to solve by updating the xml:id values? I'd start with one issue ? the file names ? and then figure out what you want to accomplish by changing xml:id values. I personally don't see much value-add with updates to the ID's, but I could be missing something! thanks, Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com From: Matt Kassawara <mkassawara at gmail.com<mailto:mkassawara at gmail.com>> Date: Monday, May 26, 2014 9:42 AM To: Diane Fleming <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>> Cc: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>>, Andreas Jaeger <aj at suse.com<mailto:aj at suse.com>>, "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>> Subject: Re: [Openstack-docs] Conventions for filenames and chapter/section IDs How about describing the hierarchy in IDs, but not necessarily with ch_, section_, etc? For example: ch_networking -> networking section_neutron-networking-ml2 -> networking-neutron-ml2 section_neutron-ml2-controller-node -> networking-neutron-ml2-controller-node Also, would it help to indicate type in figure, table, and similar element IDs? For example: example-architecture-with-legacy-networking -> fig_example-architecture-with-legacy-networking table1 -> tab_getstart-openstack-services (from common/ch_getstart.xml) para3 -> par_getstart-3 (from common/ch_getstart.xml) Or... am I still the totally crazy noob? P.S. - I'm also interested in ideas for standardizing filenames and/or locations for figures. On Sun, May 25, 2014 at 5:59 PM, Diane Fleming <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>> wrote: +1 for file name conventions -1 for xml:id conventions Sent from my iPhone On May 25, 2014, at 6:28 PM, "Anne Gentle" <anne at openstack.org<mailto:anne at openstack.org>> wrote: On Sun, May 25, 2014 at 4:50 PM, Steve Gordon <sgordon at redhat.com<mailto:sgordon at redhat.com>> wrote: ----- Original Message ----- > From: "Anne Gentle" <anne at openstack.org<mailto:anne at openstack.org>> > To: "Andreas Jaeger" <aj at suse.com<mailto:aj at suse.com>> > > Something to think about for ch and sec is that we won't always author in a > book-like manner, so let's not lock ourselves into that sort of thinking > due to current file names. > > Stick to the install guide for now, to apply conventions, just please don't > use something as meaningful semantically as chapter and section. I actually think it's important/useful information in the filename. It reflects the root node of the file's XML which has an impact on where you can nest/include it in another document (you can't include a chapter in a section for example, but you can include a section in a chapter). It's got more to do with the realities of the format being used than whether we're thinking in terms of books, articles, etc. I agree it's a useful codification in the file name, but I don't think we want it in the xml:id. The xml:id is used for SEO, for human-readable URLs, and so on. Let's not leak our abstraction further than we have to. :) Anne Granted if we moved to a non-XML format this would no longer be the case, but I think we'd have bigger conversion issues than bulk renaming the files/links. ;) -Steve _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/35a8d507/attachment.html> From nchase at mirantis.com Mon May 26 15:06:56 2014 From: nchase at mirantis.com (Nick Chase) Date: Mon, 26 May 2014 11:06:56 -0400 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CFA8BDF2.2DFA0%diane.fleming@rackspace.com> References: <CABA+jQoKAoy8OUtNNf1bwUK3jCRrYqGRx22NpH_eUuATgD0fig@mail.gmail.com> <CFA8BDF2.2DFA0%diane.fleming@rackspace.com> Message-ID: <CA+p99Gnwea4hT=bo4=W4sTOG4jVXjbi8VrgO8UmkmDx9c_WxuA@mail.gmail.com> Plus my concern in changing Id values is breaking any references. ---- Nick On May 26, 2014 10:49 AM, "Diane Fleming" <diane.fleming at rackspace.com> wrote: > Matt, > > What problem are you trying to solve by updating the xml:id values? > > I'd start with one issue ? the file names ? and then figure out what you > want to accomplish by changing xml:id values. > > I personally don't see much value-add with updates to the ID's, but I > could be missing something! > > thanks, > > *Diane* > *----------------------------------------------* > Diane Fleming > Software Developer II - US > diane.fleming at rackspace.com > Cell 512.323.6799 > Office 512.874.1260 > Skype drfleming0227 > Google-plus diane.fleming at gmail.com > > From: Matt Kassawara <mkassawara at gmail.com> > Date: Monday, May 26, 2014 9:42 AM > To: Diane Fleming <diane.fleming at rackspace.com> > Cc: Anne Gentle <anne at openstack.org>, Andreas Jaeger <aj at suse.com>, " > openstack-docs at lists.openstack.org" <openstack-docs at lists.openstack.org> > Subject: Re: [Openstack-docs] Conventions for filenames and > chapter/section IDs > > How about describing the hierarchy in IDs, but not necessarily with > ch_, section_, etc? For example: > > ch_networking -> networking > section_neutron-networking-ml2 -> networking-neutron-ml2 > section_neutron-ml2-controller-node -> > networking-neutron-ml2-controller-node > > Also, would it help to indicate type in figure, table, and similar > element IDs? For example: > > example-architecture-with-legacy-networking -> > fig_example-architecture-with-legacy-networking > table1 -> tab_getstart-openstack-services (from common/ch_getstart.xml) > para3 -> par_getstart-3 (from common/ch_getstart.xml) > > Or... am I still the totally crazy noob? > > P.S. - I'm also interested in ideas for standardizing filenames and/or > locations for figures. > > > On Sun, May 25, 2014 at 5:59 PM, Diane Fleming < > diane.fleming at rackspace.com> wrote: > >> +1 for file name conventions >> -1 for xml:id conventions >> >> >> >> Sent from my iPhone >> >> On May 25, 2014, at 6:28 PM, "Anne Gentle" <anne at openstack.org> wrote: >> >> >> >> >> On Sun, May 25, 2014 at 4:50 PM, Steve Gordon <sgordon at redhat.com> wrote: >> >>> ----- Original Message ----- >>> > From: "Anne Gentle" <anne at openstack.org> >>> > To: "Andreas Jaeger" <aj at suse.com> >>> > >>> > Something to think about for ch and sec is that we won't always author >>> in a >>> > book-like manner, so let's not lock ourselves into that sort of >>> thinking >>> > due to current file names. >>> > >>> > Stick to the install guide for now, to apply conventions, just please >>> don't >>> > use something as meaningful semantically as chapter and section. >>> >>> I actually think it's important/useful information in the filename. It >>> reflects the root node of the file's XML which has an impact on where you >>> can nest/include it in another document (you can't include a chapter in a >>> section for example, but you can include a section in a chapter). It's got >>> more to do with the realities of the format being used than whether we're >>> thinking in terms of books, articles, etc. >>> >> >> I agree it's a useful codification in the file name, but I don't think >> we want it in the xml:id. The xml:id is used for SEO, for human-readable >> URLs, and so on. Let's not leak our abstraction further than we have to. :) >> Anne >> >> >>> >>> Granted if we moved to a non-XML format this would no longer be the >>> case, but I think we'd have bigger conversion issues than bulk renaming the >>> files/links. ;) >>> >>> -Steve >>> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/df38de55/attachment-0001.html> From mkassawara at gmail.com Mon May 26 15:16:18 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Mon, 26 May 2014 09:16:18 -0600 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CFA8BDF2.2DFA0%diane.fleming@rackspace.com> References: <CABA+jQoKAoy8OUtNNf1bwUK3jCRrYqGRx22NpH_eUuATgD0fig@mail.gmail.com> <CFA8BDF2.2DFA0%diane.fleming@rackspace.com> Message-ID: <CABA+jQpEsfNWytP+yY2NGwt03rmNWPttQw-FaDbAG1YBozWuJA@mail.gmail.com> Oops... didn't reply-all the first time. IDs came up as a consistency issue from the installation guide audit. Since any changes would impact references and patches for other issues, I wanted to discuss the situation early in the process of improving the installation guide. Whatever we decide for filenames and IDs, it should go into our conventions page for future reference. On Mon, May 26, 2014 at 8:47 AM, Diane Fleming <diane.fleming at rackspace.com>wrote: > Matt, > > What problem are you trying to solve by updating the xml:id values? > > I'd start with one issue ? the file names ? and then figure out what you > want to accomplish by changing xml:id values. > > I personally don't see much value-add with updates to the ID's, but I > could be missing something! > > thanks, > > *Diane* > *----------------------------------------------* > Diane Fleming > Software Developer II - US > diane.fleming at rackspace.com > Cell 512.323.6799 > Office 512.874.1260 > Skype drfleming0227 > Google-plus diane.fleming at gmail.com > > From: Matt Kassawara <mkassawara at gmail.com> > Date: Monday, May 26, 2014 9:42 AM > To: Diane Fleming <diane.fleming at rackspace.com> > Cc: Anne Gentle <anne at openstack.org>, Andreas Jaeger <aj at suse.com>, " > openstack-docs at lists.openstack.org" <openstack-docs at lists.openstack.org> > Subject: Re: [Openstack-docs] Conventions for filenames and > chapter/section IDs > > How about describing the hierarchy in IDs, but not necessarily with > ch_, section_, etc? For example: > > ch_networking -> networking > section_neutron-networking-ml2 -> networking-neutron-ml2 > section_neutron-ml2-controller-node -> > networking-neutron-ml2-controller-node > > Also, would it help to indicate type in figure, table, and similar > element IDs? For example: > > example-architecture-with-legacy-networking -> > fig_example-architecture-with-legacy-networking > table1 -> tab_getstart-openstack-services (from common/ch_getstart.xml) > para3 -> par_getstart-3 (from common/ch_getstart.xml) > > Or... am I still the totally crazy noob? > > P.S. - I'm also interested in ideas for standardizing filenames and/or > locations for figures. > > > On Sun, May 25, 2014 at 5:59 PM, Diane Fleming < > diane.fleming at rackspace.com> wrote: > >> +1 for file name conventions >> -1 for xml:id conventions >> >> >> >> Sent from my iPhone >> >> On May 25, 2014, at 6:28 PM, "Anne Gentle" <anne at openstack.org> wrote: >> >> >> >> >> On Sun, May 25, 2014 at 4:50 PM, Steve Gordon <sgordon at redhat.com> wrote: >> >>> ----- Original Message ----- >>> > From: "Anne Gentle" <anne at openstack.org> >>> > To: "Andreas Jaeger" <aj at suse.com> >>> > >>> > Something to think about for ch and sec is that we won't always author >>> in a >>> > book-like manner, so let's not lock ourselves into that sort of >>> thinking >>> > due to current file names. >>> > >>> > Stick to the install guide for now, to apply conventions, just please >>> don't >>> > use something as meaningful semantically as chapter and section. >>> >>> I actually think it's important/useful information in the filename. It >>> reflects the root node of the file's XML which has an impact on where you >>> can nest/include it in another document (you can't include a chapter in a >>> section for example, but you can include a section in a chapter). It's got >>> more to do with the realities of the format being used than whether we're >>> thinking in terms of books, articles, etc. >>> >> >> I agree it's a useful codification in the file name, but I don't think >> we want it in the xml:id. The xml:id is used for SEO, for human-readable >> URLs, and so on. Let's not leak our abstraction further than we have to. :) >> Anne >> >> >>> >>> Granted if we moved to a non-XML format this would no longer be the >>> case, but I think we'd have bigger conversion issues than bulk renaming the >>> files/links. ;) >>> >>> -Steve >>> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/545c147a/attachment.html> From mkassawara at gmail.com Mon May 26 15:29:28 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Mon, 26 May 2014 09:29:28 -0600 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CFA8C4E9.2DFB0%diane.fleming@rackspace.com> References: <CABA+jQqq=9iQ4R5eMqmMpzS3HRQmq_6YXq7PPhbcT0+Hucs34Q@mail.gmail.com> <CFA8C4E9.2DFB0%diane.fleming@rackspace.com> Message-ID: <CABA+jQpsx6AqNC-7mzPPwLxuA74-+MVCZi_E8CnxUk85Ctm9kw@mail.gmail.com> During the Icehouse installation guide updates project, selection of IDs in new content confused me because I couldn't find conventions or anything consistent to follow. This caused me to bring up ID issues during the audit but didn't consider the underlying filename issues. For IDs, maybe we provide some good/bad examples, but otherwise leave it open to the contributor? At any rate, I'm glad this discussion revealed a larger problem that we want to fix... filenames! On Mon, May 26, 2014 at 9:17 AM, Diane Fleming <diane.fleming at rackspace.com>wrote: > Matt, > > I agree that whatever consistency issues we come up with should be > documented on conventions page. > > My suggestion was that you postpone thinking about the ID issue until > you come up with reasons for changing them. It seems like everyone agrees > on the file name changes, so I think it's safe to go forward with that! > > *Diane* > *----------------------------------------------* > Diane Fleming > Software Developer II - US > diane.fleming at rackspace.com > Cell 512.323.6799 > Office 512.874.1260 > Skype drfleming0227 > Google-plus diane.fleming at gmail.com > > From: Matt Kassawara <mkassawara at gmail.com> > Date: Monday, May 26, 2014 10:15 AM > To: Diane Fleming <diane.fleming at rackspace.com> > > Subject: Re: [Openstack-docs] Conventions for filenames and > chapter/section IDs > > IDs came up as a consistency issue from the installation guide audit. > Since any changes would impact references and patches for other issues, I > wanted to discuss the situation early in the process of improving the > installation guide. Whatever we decide for filenames and IDs, it should go > into our conventions page for future reference. > > > On Mon, May 26, 2014 at 8:47 AM, Diane Fleming < > diane.fleming at rackspace.com> wrote: > >> Matt, >> >> What problem are you trying to solve by updating the xml:id values? >> >> I'd start with one issue ? the file names ? and then figure out what >> you want to accomplish by changing xml:id values. >> >> I personally don't see much value-add with updates to the ID's, but I >> could be missing something! >> >> thanks, >> >> *Diane* >> *----------------------------------------------* >> Diane Fleming >> Software Developer II - US >> diane.fleming at rackspace.com >> Cell 512.323.6799 >> Office 512.874.1260 >> Skype drfleming0227 >> Google-plus diane.fleming at gmail.com >> >> From: Matt Kassawara <mkassawara at gmail.com> >> Date: Monday, May 26, 2014 9:42 AM >> To: Diane Fleming <diane.fleming at rackspace.com> >> Cc: Anne Gentle <anne at openstack.org>, Andreas Jaeger <aj at suse.com>, " >> openstack-docs at lists.openstack.org" <openstack-docs at lists.openstack.org> >> Subject: Re: [Openstack-docs] Conventions for filenames and >> chapter/section IDs >> >> How about describing the hierarchy in IDs, but not necessarily with >> ch_, section_, etc? For example: >> >> ch_networking -> networking >> section_neutron-networking-ml2 -> networking-neutron-ml2 >> section_neutron-ml2-controller-node -> >> networking-neutron-ml2-controller-node >> >> Also, would it help to indicate type in figure, table, and similar >> element IDs? For example: >> >> example-architecture-with-legacy-networking -> >> fig_example-architecture-with-legacy-networking >> table1 -> tab_getstart-openstack-services (from common/ch_getstart.xml) >> para3 -> par_getstart-3 (from common/ch_getstart.xml) >> >> Or... am I still the totally crazy noob? >> >> P.S. - I'm also interested in ideas for standardizing filenames and/or >> locations for figures. >> >> >> On Sun, May 25, 2014 at 5:59 PM, Diane Fleming < >> diane.fleming at rackspace.com> wrote: >> >>> +1 for file name conventions >>> -1 for xml:id conventions >>> >>> >>> >>> Sent from my iPhone >>> >>> On May 25, 2014, at 6:28 PM, "Anne Gentle" <anne at openstack.org> wrote: >>> >>> >>> >>> >>> On Sun, May 25, 2014 at 4:50 PM, Steve Gordon <sgordon at redhat.com>wrote: >>> >>>> ----- Original Message ----- >>>> > From: "Anne Gentle" <anne at openstack.org> >>>> > To: "Andreas Jaeger" <aj at suse.com> >>>> > >>>> > Something to think about for ch and sec is that we won't always >>>> author in a >>>> > book-like manner, so let's not lock ourselves into that sort of >>>> thinking >>>> > due to current file names. >>>> > >>>> > Stick to the install guide for now, to apply conventions, just please >>>> don't >>>> > use something as meaningful semantically as chapter and section. >>>> >>>> I actually think it's important/useful information in the filename. It >>>> reflects the root node of the file's XML which has an impact on where you >>>> can nest/include it in another document (you can't include a chapter in a >>>> section for example, but you can include a section in a chapter). It's got >>>> more to do with the realities of the format being used than whether we're >>>> thinking in terms of books, articles, etc. >>>> >>> >>> I agree it's a useful codification in the file name, but I don't think >>> we want it in the xml:id. The xml:id is used for SEO, for human-readable >>> URLs, and so on. Let's not leak our abstraction further than we have to. :) >>> Anne >>> >>> >>>> >>>> Granted if we moved to a non-XML format this would no longer be the >>>> case, but I think we'd have bigger conversion issues than bulk renaming the >>>> files/links. ;) >>>> >>>> -Steve >>>> >>> >>> _______________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.openstack.org >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>> >>> >>> _______________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.openstack.org >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>> >>> >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/97840a1d/attachment-0001.html> From nchase at mirantis.com Mon May 26 15:32:00 2014 From: nchase at mirantis.com (Nick Chase) Date: Mon, 26 May 2014 11:32:00 -0400 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <1965553805.18459527.1401054641947.JavaMail.zimbra@redhat.com> References: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> <53824983.3060301@suse.com> <CAD0KtVFPYs7LdCYUunnD5Yk1qvoCAcoUvjgkVDbW2YyuNSU0Xg@mail.gmail.com> <1965553805.18459527.1401054641947.JavaMail.zimbra@redhat.com> Message-ID: <CA+p99GkhBPhxsEzKeu=45DwYWuVfq=pozVKzTO2Tz7O6RM162A@mail.gmail.com> OK, so as I'm breaking out the HA chapter at this very minute, let me throw something else into the mix. The HA Guide is broken into 2 parts, each with a number of chapters, each with a number of sections. Right now I've broken it down into chapter files, but as I get down to the section level I begin to get overwhelmed with the number of files. Is there any objection to grouping section files in folders by chapter? For example: ch_aa_network.xml ch_aa_network/sec_run_neutron_dhcp_agent.xml I mean, I can just as easily make it ch_aa_network.xml sec_run_neutron_dhcp_agent.xml But it starts to get really messy. Thoughts? ---- Nick On Sun, May 25, 2014 at 5:50 PM, Steve Gordon <sgordon at redhat.com> wrote: > ----- Original Message ----- > > From: "Anne Gentle" <anne at openstack.org> > > To: "Andreas Jaeger" <aj at suse.com> > > > > Something to think about for ch and sec is that we won't always author > in a > > book-like manner, so let's not lock ourselves into that sort of thinking > > due to current file names. > > > > Stick to the install guide for now, to apply conventions, just please > don't > > use something as meaningful semantically as chapter and section. > > I actually think it's important/useful information in the filename. It > reflects the root node of the file's XML which has an impact on where you > can nest/include it in another document (you can't include a chapter in a > section for example, but you can include a section in a chapter). It's got > more to do with the realities of the format being used than whether we're > thinking in terms of books, articles, etc. > > Granted if we moved to a non-XML format this would no longer be the case, > but I think we'd have bigger conversion issues than bulk renaming the > files/links. ;) > > -Steve > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/fb151b87/attachment.html> From david.cramer at RACKSPACE.COM Mon May 26 15:43:52 2014 From: david.cramer at RACKSPACE.COM (David Cramer) Date: Mon, 26 May 2014 15:43:52 +0000 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs References: <CABA+jQoKAoy8OUtNNf1bwUK3jCRrYqGRx22NpH_eUuATgD0fig@mail.gmail.com> <CFA8BDF2.2DFA0%diane.fleming@rackspace.com> <CA+p99Gnwea4hT=bo4=W4sTOG4jVXjbi8VrgO8UmkmDx9c_WxuA@mail.gmail.com> Message-ID: <911A41E5F7881A4C8DE8BE32135554A9A1CB8C21@ORD1EXD01.RACKSPACE.CORP> On 5/26/14, 10:07 AM, Nick Chase wrote: > Plus my concern in changing Id values is breaking any references. You can reduce (but not eliminate) the impact of a file name change by changing the file names via a processing instruction: <section xml:id="some-dumb-id"><?dbhtml filename="intro.html"?>... If you use <?dbhtml filename="..."?> you'll get the aesthetically pleasing intro.html file name without having to change the xml:id and break xrefs to the section. However, if you have external links to some-dumb-id.html from other documents, those links would obviously break. Regardless of the publishing tool chain, when changing the names of existing resources on the web, the best approach is to add 301 redirects to avoid breaking bookmarks, links, and losing SEO karma. Regards, David From mkassawara at gmail.com Mon May 26 15:53:27 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Mon, 26 May 2014 09:53:27 -0600 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CA+p99GkhBPhxsEzKeu=45DwYWuVfq=pozVKzTO2Tz7O6RM162A@mail.gmail.com> References: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> <53824983.3060301@suse.com> <CAD0KtVFPYs7LdCYUunnD5Yk1qvoCAcoUvjgkVDbW2YyuNSU0Xg@mail.gmail.com> <1965553805.18459527.1401054641947.JavaMail.zimbra@redhat.com> <CA+p99GkhBPhxsEzKeu=45DwYWuVfq=pozVKzTO2Tz7O6RM162A@mail.gmail.com> Message-ID: <CABA+jQrQdT92N6yV1kpLMGGUc3yCbR-VgLkyGyGaZgp0cLJeRw@mail.gmail.com> I like the idea of subdirectories. During the installation guide updates project, I broke the neutron content into smaller files to simplify editing and to reduce chances of patch collisions. However, this increased the overall number of files. Implementing subdirectories would mitigate this issue. The installation guide swift chapter already uses a subdirectory which I'm debating suggesting for the remainder of the installation guide and potentially other books. On Mon, May 26, 2014 at 9:32 AM, Nick Chase <nchase at mirantis.com> wrote: > OK, so as I'm breaking out the HA chapter at this very minute, let me > throw something else into the mix. The HA Guide is broken into 2 parts, > each with a number of chapters, each with a number of sections. Right now > I've broken it down into chapter files, but as I get down to the section > level I begin to get overwhelmed with the number of files. Is there any > objection to grouping section files in folders by chapter? For example: > > ch_aa_network.xml > ch_aa_network/sec_run_neutron_dhcp_agent.xml > > I mean, I can just as easily make it > > ch_aa_network.xml > sec_run_neutron_dhcp_agent.xml > > But it starts to get really messy. > > Thoughts? > > ---- Nick > > > > On Sun, May 25, 2014 at 5:50 PM, Steve Gordon <sgordon at redhat.com> wrote: > >> ----- Original Message ----- >> > From: "Anne Gentle" <anne at openstack.org> >> > To: "Andreas Jaeger" <aj at suse.com> >> > >> > Something to think about for ch and sec is that we won't always author >> in a >> > book-like manner, so let's not lock ourselves into that sort of thinking >> > due to current file names. >> > >> > Stick to the install guide for now, to apply conventions, just please >> don't >> > use something as meaningful semantically as chapter and section. >> >> I actually think it's important/useful information in the filename. It >> reflects the root node of the file's XML which has an impact on where you >> can nest/include it in another document (you can't include a chapter in a >> section for example, but you can include a section in a chapter). It's got >> more to do with the realities of the format being used than whether we're >> thinking in terms of books, articles, etc. >> >> Granted if we moved to a non-XML format this would no longer be the case, >> but I think we'd have bigger conversion issues than bulk renaming the >> files/links. ;) >> >> -Steve >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/791df983/attachment.html> From diane.fleming at RACKSPACE.COM Mon May 26 15:55:19 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Mon, 26 May 2014 15:55:19 +0000 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CABA+jQrQdT92N6yV1kpLMGGUc3yCbR-VgLkyGyGaZgp0cLJeRw@mail.gmail.com> Message-ID: <CFA8CE0C.2DFBF%diane.fleming@rackspace.com> +1 subdirectories Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com From: Matt Kassawara <mkassawara at gmail.com<mailto:mkassawara at gmail.com>> Date: Monday, May 26, 2014 10:53 AM To: Nick Chase <nchase at mirantis.com<mailto:nchase at mirantis.com>> Cc: Andreas Jaeger <aj at suse.com<mailto:aj at suse.com>>, "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>> Subject: Re: [Openstack-docs] Conventions for filenames and chapter/section IDs I like the idea of subdirectories. During the installation guide updates project, I broke the neutron content into smaller files to simplify editing and to reduce chances of patch collisions. However, this increased the overall number of files. Implementing subdirectories would mitigate this issue. The installation guide swift chapter already uses a subdirectory which I'm debating suggesting for the remainder of the installation guide and potentially other books. On Mon, May 26, 2014 at 9:32 AM, Nick Chase <nchase at mirantis.com<mailto:nchase at mirantis.com>> wrote: OK, so as I'm breaking out the HA chapter at this very minute, let me throw something else into the mix. The HA Guide is broken into 2 parts, each with a number of chapters, each with a number of sections. Right now I've broken it down into chapter files, but as I get down to the section level I begin to get overwhelmed with the number of files. Is there any objection to grouping section files in folders by chapter? For example: ch_aa_network.xml ch_aa_network/sec_run_neutron_dhcp_agent.xml I mean, I can just as easily make it ch_aa_network.xml sec_run_neutron_dhcp_agent.xml But it starts to get really messy. Thoughts? ---- Nick On Sun, May 25, 2014 at 5:50 PM, Steve Gordon <sgordon at redhat.com<mailto:sgordon at redhat.com>> wrote: ----- Original Message ----- > From: "Anne Gentle" <anne at openstack.org<mailto:anne at openstack.org>> > To: "Andreas Jaeger" <aj at suse.com<mailto:aj at suse.com>> > > Something to think about for ch and sec is that we won't always author in a > book-like manner, so let's not lock ourselves into that sort of thinking > due to current file names. > > Stick to the install guide for now, to apply conventions, just please don't > use something as meaningful semantically as chapter and section. I actually think it's important/useful information in the filename. It reflects the root node of the file's XML which has an impact on where you can nest/include it in another document (you can't include a chapter in a section for example, but you can include a section in a chapter). It's got more to do with the realities of the format being used than whether we're thinking in terms of books, articles, etc. Granted if we moved to a non-XML format this would no longer be the case, but I think we'd have bigger conversion issues than bulk renaming the files/links. ;) -Steve _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/86fc4365/attachment-0001.html> From nchase at mirantis.com Mon May 26 16:13:40 2014 From: nchase at mirantis.com (Nick Chase) Date: Mon, 26 May 2014 12:13:40 -0400 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <911A41E5F7881A4C8DE8BE32135554A9A1CB8C21@ORD1EXD01.RACKSPACE.CORP> References: <CABA+jQoKAoy8OUtNNf1bwUK3jCRrYqGRx22NpH_eUuATgD0fig@mail.gmail.com> <CFA8BDF2.2DFA0%diane.fleming@rackspace.com> <CA+p99Gnwea4hT=bo4=W4sTOG4jVXjbi8VrgO8UmkmDx9c_WxuA@mail.gmail.com> <911A41E5F7881A4C8DE8BE32135554A9A1CB8C21@ORD1EXD01.RACKSPACE.CORP> Message-ID: <CA+p99GnUAz0Z+CqzXutLAWkei51JjVp-H84AdYx+s6s_AHvPzA@mail.gmail.com> My concern on this is that it raises a barrier to entry for contributors. It's not intuitive. As a fix in an emergency, sure. But I'd be concerned about building this out as the standard way we do things. ---- Nick On Mon, May 26, 2014 at 11:43 AM, David Cramer <david.cramer at rackspace.com>wrote: > On 5/26/14, 10:07 AM, Nick Chase wrote: > > Plus my concern in changing Id values is breaking any references. > > You can reduce (but not eliminate) the impact of a file name change by > changing the file names via a processing instruction: > > <section xml:id="some-dumb-id"><?dbhtml filename="intro.html"?>... > > If you use <?dbhtml filename="..."?> you'll get the aesthetically > pleasing intro.html file name without having to change the xml:id and > break xrefs to the section. However, if you have external links to > some-dumb-id.html from other documents, those links would obviously break. > > Regardless of the publishing tool chain, when changing the names of > existing resources on the web, the best approach is to add 301 redirects > to avoid breaking bookmarks, links, and losing SEO karma. > > Regards, > David > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/8eaa2917/attachment.html> From nchase at mirantis.com Mon May 26 19:52:13 2014 From: nchase at mirantis.com (Nick Chase) Date: Mon, 26 May 2014 15:52:13 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CA+p99GnrsU07jj7j+=bb7B0=k8_rPDnN2fQmNdN_WDC=D14jhg@mail.gmail.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> <53824AA5.8020702@suse.com> <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> <CFA8BF47.13C7%joseph.robinson@rackspace.com> <CA+p99Gn3cBBKW1cXX1seXuoUfd7Ahn9vNLw=nL734T_kABwmpA@mail.gmail.com> <5382DE71.2080908@suse.com> <CA+p99GnrsU07jj7j+=bb7B0=k8_rPDnN2fQmNdN_WDC=D14jhg@mail.gmail.com> Message-ID: <CA+p99G=Gj3vx2mRwC1u74qS34VS1-Kw77HoPkMTG1tKNWdeSPQ@mail.gmail.com> OK, as soon as https://review.openstack.org/#/c/95401/ merges, I've got the files broken out by section and ready to go. ---- Nick On Mon, May 26, 2014 at 10:39 AM, Nick Chase <nchase at mirantis.com> wrote: > > On May 26, 2014 2:25 AM, "Andreas Jaeger" <aj at suse.com> wrote: > > > > On 05/26/2014 07:44 AM, Nick Chase wrote: > > > OK, so here's where we are: > > > > > > I've got one patch in that does the wholesale conversion to XML, but > > > doesn't have things broken down and audited yet. That's here: > > > > > > https://review.openstack.org/#/c/95401/ > > > > > > However, as you can see, it doesn't pass tox. It doesn't pass tox > > > locally because it's trying to convert it to docbook, and there's > > > nothing to convert. I've removed that functionality from os-docs-tools > > > here: > > > > > > https://review.openstack.org/#/c/95406/ > > > > > > But that needs to be merged before I can run tox on the book to look > for > > > other problems. I think. > > > > Agreed. I should have read my whole INBOX before patching and answering > ;) > > If you're like me you'd never get anything done that way. :) > > > > Anyway, I've just commented code here; I'm happy to actually delete it > > > if I've done the right thing, but I didn't want to just hack out a > bunch > > > of code without someone more familiar looking at it first. > > > > You commented out too much in that file and missed the parts that > > actually builds the books, I've updated your patch. > > And that's why I commented instead of deleting. :) Thanks for the assist. > > Anyway I've got the next one, which breaks it all down to the section > level, just about ready to go. Then i can do cleanup. > > ---- Nick > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/2d7be7ed/attachment.html> From gauvain.pocentek at objectif-libre.com Tue May 27 15:15:16 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Tue, 27 May 2014 17:15:16 +0200 Subject: [Openstack-docs] [openstack-dev] [Heat][Documentation] Heat template documentation In-Reply-To: <CAD0KtVEyJmezeHhQqZXBwUwS9-cbafYp9sCcEp=ybiWuiKtUzw@mail.gmail.com> References: <CAD0KtVF6qnO4-Kd7ELxJZU53r7jtTSv7mCJG3ZVyJu-C+LxtYA@mail.gmail.com> <37903930f5456fa6f09066fe41cce960@objectif-libre.com> <CADb+p3RJ=cO0BxRsp7p=QiScS72dg5+ruz4WFZS9ZqyjE3sYcA@mail.gmail.com> <537BE872.3090509@redhat.com> <CAD0KtVHiqMgEq-A3ozq2ZVx3PtAZ=jwUnWHfa=pht5WXnLMHtA@mail.gmail.com> <537E6B94.1090806@redhat.com> <20140523101315.GA22280@t430slt.redhat.com> <537F2530.8010905@suse.com> <20140523111957.GB22280@t430slt.redhat.com> <CAD0KtVHP_=Og1uyL_p_k0+5nSk-8mJHFtOPbXqu-mO8R7QXg8Q@mail.gmail.com> <20140523134251.GC22280@t430slt.redhat.com> <CAD0KtVEyJmezeHhQqZXBwUwS9-cbafYp9sCcEp=ybiWuiKtUzw@mail.gmail.com> Message-ID: <f27ea5d694bbb2f800575c22266f0d39@objectif-libre.com> Le 2014-05-23 15:57, Anne Gentle a ?crit?: > On Fri, May 23, 2014 at 8:42 AM, Steven Hardy <shardy at redhat.com> > wrote: > >> On Fri, May 23, 2014 at 08:09:06AM -0500, Anne Gentle wrote: >>> On Fri, May 23, 2014 at 6:19 AM, Steven Hardy <shardy at redhat.com> >>> wrote: >>> >>>> On Fri, May 23, 2014 at 12:38:40PM +0200, Andreas Jaeger wrote: >>>>> On 05/23/2014 12:13 PM, Steven Hardy wrote: >>>>>> [...] >>>>>> I'll hold my hand up as one developer who tried to contribute but >>>>>> ran >>>> away >>>>>> screaming due to all the XML-java-ness of the current process. >>>>>> I don't think markup complexity is a major barrier to >>>>>> contribution. >>>> Needing >>>>>> to use a closed source editor and download unfathomably huge >>>>>> amounts of >>>>>> java to build locally definitely are though IMO/IME. >>>>> You do not need a closed sourced editor for XML - I'm using emacs >>>>> and >>>>> others in the team use vi for it. >>>> Sure, maybe "need" was the wrong word to use, my apologies. >>>> ?Regardless, >>>> the docs refer to a closed source tool being "encouraged", which >>>> immediately discouraged me when trying to figure out the workflow. >>>> I've tried editing XML in vim a few times, and although it's >>>> obviously >>>> possible, it's far less painful when I'm dealing with other more >>>> human-friendly formats. >>>> >>>>> Yes, it downloads a lot Java once. We also now build the documents >>>>> as >>>>> part of the gate, so you can also check changes by clicking the >>>>> "checkbuild" target, it will show you the converted books, >>>> Sure, that's good, but my (and I'd guess many others) preference is >>>> for >>>> formats which can be easily built locally with only distro-provided >>>> tools, >>>> not a huge pile of third party java. >>>> Not trying to start a format-advocacy argument here, just trying to >>>> provide >>>> a data-point that, if the success criteria is developer >>>> participation in >>>> the docs process, then the current toolchain is definitely a >>>> barrier to >>>> participation for some potential contributors. >>>> >>> >>> Thanks for the discussions -- let's keep a tone of civility. >>> Understand >>> that doc writers have specific tools that work well for them. That >>> said, we >>> do want to collaborate more with our end users specifically. >> My apologies if my remarks have been interpreted as uncivil, that was >> definitely not my intention. > Oh no not at all, sorry -- my intent is that we are all staying civil > and it's good. :) > ? > >> The only point I really wanted to convey was +1 on trying out an >> easier >> markup, and thanks for bringing up the topic of a user orientated >> orchestration guide - I would definitely like to contribute to the >> effort. > So we're still a little stuck on the tradeoffs -- with easier markup > we lose some features.? > For other generated reference docs, we maintain a set of python > scripts in openstack-doc-tools. Is it possible for someone to look > into generating the Heat template reference information outside of > Sphinx? Yes, I can look into that. The idea would be to generate some docbook from RST... So why not do it for the whole to-be-written heat user guide in that case? What I get from this thread is that 1) docbook is the best format to use to generate a nice and feature-rich output, 2) developers don't want to write docbook. Without being able to handle a different format developers will no contribute, which is bad because they want, and we want them to contribute :) So my feeling is that we should work on the tools to convert RST (or whatever format, but RST seems to be the "norm" for openstack projects) to docbook, and generate our online documentation from there. There are tools that can help us doing that, and I don't see an other solution that would make us move forward. Anne, you talked about experimenting with the end user guide, and after the discussion and the technical info brought by Doug, Steve and Steven, I now think it is worth trying. Thoughts? Gauvain From aj at suse.com Tue May 27 19:01:56 2014 From: aj at suse.com (Andreas Jaeger) Date: Tue, 27 May 2014 21:01:56 +0200 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <537CACFE.7090604@b1-systems.de> References: <537CACFE.7090604@b1-systems.de> Message-ID: <5384E124.3020201@suse.com> On 05/21/2014 03:41 PM, Christian Berendt wrote: > Even I like AsciiDoc I would suggest to convert the HA guide from > AsciiDoc to DocBook. All other guides are written in DocBox and I don't > see any benefit of keeping the HA guide in AsciiDoc. FYI, the patch by Nick has just been merged! This needs version 0.15 of the openstack-doc-tools. Anne just released the version. So, if you build locally, remember that you don't need to convert from asciidoc to docbook anymore - and if you use openstack-doc-tools, you need the 0.15 version for taking care of this. Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From nchase at mirantis.com Tue May 27 19:11:14 2014 From: nchase at mirantis.com (Nicholas Chase) Date: Tue, 27 May 2014 15:11:14 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <5384E124.3020201@suse.com> References: <537CACFE.7090604@b1-systems.de> <5384E124.3020201@suse.com> Message-ID: <5384E352.3030109@mirantis.com> Yay! OK, now I've got a question for you git folks out there. Yesterday, I did the next step in this process, breaking everything down by chapter and section. I got so far as to commit, but I decided to wait before hitting "git review". Today those files are GONE. Looks like my working copy has reset itself to an earlier version. I can redo it, but it took quite a while so I'd prefer to just retrieve it somehow. Does anybody have any ideas? Thanks... ---- Nick On 5/27/2014 3:01 PM, Andreas Jaeger wrote: > On 05/21/2014 03:41 PM, Christian Berendt wrote: >> Even I like AsciiDoc I would suggest to convert the HA guide from >> AsciiDoc to DocBook. All other guides are written in DocBox and I don't >> see any benefit of keeping the HA guide in AsciiDoc. > > FYI, the patch by Nick has just been merged! > > This needs version 0.15 of the openstack-doc-tools. Anne just released > the version. So, if you build locally, remember that you don't need to > convert from asciidoc to docbook anymore - and if you use > openstack-doc-tools, you need the 0.15 version for taking care of this. > > Andreas > From aj at suse.com Tue May 27 20:27:50 2014 From: aj at suse.com (Andreas Jaeger) Date: Tue, 27 May 2014 22:27:50 +0200 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <5384E352.3030109@mirantis.com> References: <537CACFE.7090604@b1-systems.de> <5384E124.3020201@suse.com> <5384E352.3030109@mirantis.com> Message-ID: <5384F546.2010707@suse.com> On 05/27/2014 09:11 PM, Nicholas Chase wrote: > Yay! OK, now I've got a question for you git folks out there. > > Yesterday, I did the next step in this process, breaking everything down > by chapter and section. I got so far as to commit, but I decided to > wait before hitting "git review". > > Today those files are GONE. Looks like my working copy has reset itself > to an earlier version. > > I can redo it, but it took quite a while so I'd prefer to just retrieve > it somehow. Does anybody have any ideas? > > Thanks... Are you working on a separate branch for this and just need to switch to it? IF not, do it next time ;) If you commit it, is it on your master branch, just not at the top of it? Run "git log" and search whether you can find it. Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From nchase at mirantis.com Tue May 27 20:35:05 2014 From: nchase at mirantis.com (Nicholas Chase) Date: Tue, 27 May 2014 16:35:05 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <5384F546.2010707@suse.com> References: <537CACFE.7090604@b1-systems.de> <5384E124.3020201@suse.com> <5384E352.3030109@mirantis.com> <5384F546.2010707@suse.com> Message-ID: <5384F6F9.9050902@mirantis.com> The weird thing is that I DID switch to a branch to work on it, but I'm not seeing the branch anywhere, even though I was able to see it yesterday when I listed branches. ---- Nick On 5/27/2014 4:27 PM, Andreas Jaeger wrote: > On 05/27/2014 09:11 PM, Nicholas Chase wrote: >> Yay! OK, now I've got a question for you git folks out there. >> >> Yesterday, I did the next step in this process, breaking everything down >> by chapter and section. I got so far as to commit, but I decided to >> wait before hitting "git review". >> >> Today those files are GONE. Looks like my working copy has reset itself >> to an earlier version. >> >> I can redo it, but it took quite a while so I'd prefer to just retrieve >> it somehow. Does anybody have any ideas? >> >> Thanks... > > > Are you working on a separate branch for this and just need to switch to > it? IF not, do it next time ;) > > If you commit it, is it on your master branch, just not at the top of > it? Run "git log" and search whether you can find it. > > Andreas > From openstack at lanabrindley.com Tue May 27 23:35:59 2014 From: openstack at lanabrindley.com (Lana Brindley) Date: Wed, 28 May 2014 09:35:59 +1000 Subject: [Openstack-docs] APAC docs meeting CANCELLED Message-ID: <5385215F.7040102@lanabrindley.com> Heya everyone, Unless someone (Summer?) can stand up to be chair at the last minute, I'm afraid I have to cancel today's APAC OpenStack docs meeting, as I have a conflict. I'll see you in two weeks o/ L -- Lana Brindley Technical Writer Rackspace Cloud Builders Australia http://lanabrindley.com From mkassawara at gmail.com Tue May 27 23:42:57 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Tue, 27 May 2014 17:42:57 -0600 Subject: [Openstack-docs] APAC docs meeting CANCELLED In-Reply-To: <5385215F.7040102@lanabrindley.com> References: <5385215F.7040102@lanabrindley.com> Message-ID: <CABA+jQqm1=_5C=dQC3Os8FMCnuF8Qq8rMmwfee0Da5mqnhgNjA@mail.gmail.com> I can chair the meeting. Please add any topics to the wiki page. https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting#Agenda_for_next_meeting On Tue, May 27, 2014 at 5:35 PM, Lana Brindley <openstack at lanabrindley.com>wrote: > Heya everyone, > > Unless someone (Summer?) can stand up to be chair at the last minute, I'm > afraid I have to cancel today's APAC OpenStack docs meeting, as I have a > conflict. > > I'll see you in two weeks o/ > > L > > -- > Lana Brindley > Technical Writer > Rackspace Cloud Builders Australia > http://lanabrindley.com > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140527/1f0491d0/attachment.html> From anne at openstack.org Wed May 28 04:04:10 2014 From: anne at openstack.org (Anne Gentle) Date: Tue, 27 May 2014 23:04:10 -0500 Subject: [Openstack-docs] Alternating meetings Wed. Message-ID: <CAD0KtVFXHTiTsaXk-re+QAdKH_5kwcYuWP+2+jgUWPZ_3kizkQ@mail.gmail.com> Hi all, Typically I rely on the ical feed to tell me when the Docs team meeting is, but it seems that the ical feed thinks the North America meeting is the 1st and 3rd Wed. and it had "forgotten" the APAC meeting. I've now coerced it to remember the APAC meeting as 0300 UTC on the 2nd and 4th Wed. I hope this fits reality and we can run an APAC meeting tomorrow. Let me know - Thanks, Anne -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140527/14c6e760/attachment-0001.html> From gauvain.pocentek at objectif-libre.com Wed May 28 05:17:41 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Wed, 28 May 2014 07:17:41 +0200 Subject: [Openstack-docs] [openstack-dev] [Heat][Documentation] Heat template documentation In-Reply-To: <53853639.2020506@redhat.com> References: <CAD0KtVF6qnO4-Kd7ELxJZU53r7jtTSv7mCJG3ZVyJu-C+LxtYA@mail.gmail.com> <37903930f5456fa6f09066fe41cce960@objectif-libre.com> <CADb+p3RJ=cO0BxRsp7p=QiScS72dg5+ruz4WFZS9ZqyjE3sYcA@mail.gmail.com> <537BE872.3090509@redhat.com> <CAD0KtVHiqMgEq-A3ozq2ZVx3PtAZ=jwUnWHfa=pht5WXnLMHtA@mail.gmail.com> <537E6B94.1090806@redhat.com> <20140523101315.GA22280@t430slt.redhat.com> <537F2530.8010905@suse.com> <20140523111957.GB22280@t430slt.redhat.com> <CAD0KtVHP_=Og1uyL_p_k0+5nSk-8mJHFtOPbXqu-mO8R7QXg8Q@mail.gmail.com> <20140523134251.GC22280@t430slt.redhat.com> <CAD0KtVEyJmezeHhQqZXBwUwS9-cbafYp9sCcEp=ybiWuiKtUzw@mail.gmail.com> <f27ea5d694bbb2f800575c22266f0d39@objectif-libre.com> <53853639.2020506@redhat.com> Message-ID: <0ffd733cc476e5b3ed39bb5be83bd5f7@objectif-libre.com> Le 2014-05-28 03:04, Steve Baker a ?crit?: > On 28/05/14 03:15, Gauvain Pocentek wrote: >> Le 2014-05-23 15:57, Anne Gentle a ?crit : >>> On Fri, May 23, 2014 at 8:42 AM, Steven Hardy <shardy at redhat.com> >>> wrote: >>> >>>> On Fri, May 23, 2014 at 08:09:06AM -0500, Anne Gentle wrote: >>>>> On Fri, May 23, 2014 at 6:19 AM, Steven Hardy <shardy at redhat.com> >>>>> wrote: >>>>> >>>>>> On Fri, May 23, 2014 at 12:38:40PM +0200, Andreas Jaeger wrote: >>>>>>> On 05/23/2014 12:13 PM, Steven Hardy wrote: >>>>>>>> [...] >>>>>>>> I'll hold my hand up as one developer who tried to contribute >>>>>>>> but ran >>>>>> away >>>>>>>> screaming due to all the XML-java-ness of the current process. >>>>>>>> I don't think markup complexity is a major barrier to >>>>>>>> contribution. >>>>>> Needing >>>>>>>> to use a closed source editor and download unfathomably huge >>>>>>>> amounts of >>>>>>>> java to build locally definitely are though IMO/IME. >>>>>>> You do not need a closed sourced editor for XML - I'm using >>>>>>> emacs >>>>>>> and >>>>>>> others in the team use vi for it. >>>>>> Sure, maybe "need" was the wrong word to use, my apologies. >>>>>> Regardless, >>>>>> the docs refer to a closed source tool being "encouraged", which >>>>>> immediately discouraged me when trying to figure out the >>>>>> workflow. >>>>>> I've tried editing XML in vim a few times, and although it's >>>>>> obviously >>>>>> possible, it's far less painful when I'm dealing with other more >>>>>> human-friendly formats. >>>>>> >>>>>>> Yes, it downloads a lot Java once. We also now build the >>>>>>> documents as >>>>>>> part of the gate, so you can also check changes by clicking the >>>>>>> "checkbuild" target, it will show you the converted books, >>>>>> Sure, that's good, but my (and I'd guess many others) preference >>>>>> is for >>>>>> formats which can be easily built locally with only >>>>>> distro-provided tools, >>>>>> not a huge pile of third party java. >>>>>> Not trying to start a format-advocacy argument here, just trying >>>>>> to provide >>>>>> a data-point that, if the success criteria is developer >>>>>> participation in >>>>>> the docs process, then the current toolchain is definitely a >>>>>> barrier to >>>>>> participation for some potential contributors. >>>>>> >>>>> >>>>> Thanks for the discussions -- let's keep a tone of civility. >>>>> Understand >>>>> that doc writers have specific tools that work well for them. That >>>>> said, we >>>>> do want to collaborate more with our end users specifically. >>>> My apologies if my remarks have been interpreted as uncivil, that >>>> was >>>> definitely not my intention. >>> Oh no not at all, sorry -- my intent is that we are all staying >>> civil >>> and it's good. :) >>> >>> >>>> The only point I really wanted to convey was +1 on trying out an >>>> easier >>>> markup, and thanks for bringing up the topic of a user orientated >>>> orchestration guide - I would definitely like to contribute to the >>>> effort. >>> So we're still a little stuck on the tradeoffs -- with easier markup >>> we lose some features. >>> For other generated reference docs, we maintain a set of python >>> scripts in openstack-doc-tools. Is it possible for someone to look >>> into generating the Heat template reference information outside of >>> Sphinx? >> >> Yes, I can look into that. >> >> The idea would be to generate some docbook from RST... So why not do >> it for the whole to-be-written heat user guide in that case? >> >> What I get from this thread is that 1) docbook is the best format to >> use to generate a nice and feature-rich output, 2) developers don't >> want to write docbook. Without being able to handle a different >> format >> developers will no contribute, which is bad because they want, and we >> want them to contribute :) >> >> So my feeling is that we should work on the tools to convert RST (or >> whatever format, but RST seems to be the "norm" for openstack >> projects) to docbook, and generate our online documentation from >> there. There are tools that can help us doing that, and I don't see >> an >> other solution that would make us move forward. >> >> Anne, you talked about experimenting with the end user guide, and >> after the discussion and the technical info brought by Doug, Steve >> and >> Steven, I now think it is worth trying. >> > In this vein, I enabled the sphinx xml builder in heat: > https://review.openstack.org/#/c/95979/ > > And here is a sample of the output: > http://paste.openstack.org/show/81811/ > http://paste.openstack.org/show/81812/ > > This looks like it could be readily transformed into DocBook via XSL. http://ebellot.chez.com/dn2dbk/index.htm could be used as a starting point. It generates docbook 4, but can probably be easily modified to generate docbook 5, adapted to our conventions. The doc is in french, if anyone's interested I can do a quick translation of the important parts. > Alternatively we could write a Docutils writer which writes docbook > directly, possibly using this as a starting point: > http://docutils.sourceforge.net/sandbox/oliverr/docbook/ > > Any takers to start playing with this? I need to dive into docutils writers to understand/maintain an internal tool of ours, so /me volunteers. I also looked at how pandoc handles the RST -> docbook conversion, but I don't think it's not good enough for our needs. I'll play with these tools this week to see which one is the best option for us. Thanks! Gauvain From aj at suse.com Wed May 28 07:02:19 2014 From: aj at suse.com (Andreas Jaeger) Date: Wed, 28 May 2014 09:02:19 +0200 Subject: [Openstack-docs] Merging glossary back from O'Reilly guide with indexterms? Message-ID: <538589FB.60407@suse.com> The glossary in the O'Reilly guide has now lots of indexterm. To keep operations-guide and openstack-manuals in sync, I suggest to sync these - and thus include all the indexterms also in the openstack-manuals glossary. Any better suggestions? Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Wed May 28 08:20:17 2014 From: aj at suse.com (Andreas Jaeger) Date: Wed, 28 May 2014 10:20:17 +0200 Subject: [Openstack-docs] Japanese End User Guide and Admin User Guide Message-ID: <53859C41.9060706@suse.com> The Japanese team has done a great job translating these two guides! I just tried to build them and got hit by build errors. Could somebody investigate this, please? Once it works again, tell me and I can enable testing and publishing in openstack-manuals. I filled a bug for tracking: https://bugs.launchpad.net/openstack-i18n/+bug/1324007 Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Wed May 28 14:04:22 2014 From: anne at openstack.org (Anne Gentle) Date: Wed, 28 May 2014 09:04:22 -0500 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CA+p99GnUAz0Z+CqzXutLAWkei51JjVp-H84AdYx+s6s_AHvPzA@mail.gmail.com> References: <CABA+jQoKAoy8OUtNNf1bwUK3jCRrYqGRx22NpH_eUuATgD0fig@mail.gmail.com> <CFA8BDF2.2DFA0%diane.fleming@rackspace.com> <CA+p99Gnwea4hT=bo4=W4sTOG4jVXjbi8VrgO8UmkmDx9c_WxuA@mail.gmail.com> <911A41E5F7881A4C8DE8BE32135554A9A1CB8C21@ORD1EXD01.RACKSPACE.CORP> <CA+p99GnUAz0Z+CqzXutLAWkei51JjVp-H84AdYx+s6s_AHvPzA@mail.gmail.com> Message-ID: <CAD0KtVEm4pEwP2RVPah20SgjSruALXq9Cpq-imHsThnMrkbUug@mail.gmail.com> Here's what I'll update in the Documentation/Conventions page if everyone agrees: For file names, use bk_ ch_ and sec_ at the beginning of the file name to indicate the type of file it is in the hierarchy of the build. For further organization, you can use subdirectories to organize the files by a particular grouping such as project or topic. For xml:id creation, follow these guidelines. - xml:id must be unique across a built deliverable, otherwise you get build errors - xml:id creates the HTML file name so it should be human-readable, not codified like the file name - xml:id should closely follow the actual title in the text, using dashes for spaces - xml:id creation should consider search and find-ability as well as human-readability I prefer not to document the use a processing instruction like <?dbhtml filename="name"> as that should be the rare exception. Thanks, Anne On Mon, May 26, 2014 at 11:13 AM, Nick Chase <nchase at mirantis.com> wrote: > My concern on this is that it raises a barrier to entry for contributors. > It's not intuitive. As a fix in an emergency, sure. But I'd be concerned > about building this out as the standard way we do things. > > ---- Nick > > > On Mon, May 26, 2014 at 11:43 AM, David Cramer <david.cramer at rackspace.com > > wrote: > >> On 5/26/14, 10:07 AM, Nick Chase wrote: >> > Plus my concern in changing Id values is breaking any references. >> >> You can reduce (but not eliminate) the impact of a file name change by >> changing the file names via a processing instruction: >> >> <section xml:id="some-dumb-id"><?dbhtml filename="intro.html"?>... >> >> If you use <?dbhtml filename="..."?> you'll get the aesthetically >> pleasing intro.html file name without having to change the xml:id and >> break xrefs to the section. However, if you have external links to >> some-dumb-id.html from other documents, those links would obviously break. >> >> Regardless of the publishing tool chain, when changing the names of >> existing resources on the web, the best approach is to add 301 redirects >> to avoid breaking bookmarks, links, and losing SEO karma. >> >> Regards, >> David >> >> > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140528/d517f9c0/attachment.html> From anne at openstack.org Wed May 28 14:09:25 2014 From: anne at openstack.org (Anne Gentle) Date: Wed, 28 May 2014 09:09:25 -0500 Subject: [Openstack-docs] What's Up Doc? May 28 2014 Message-ID: <CAD0KtVE+BCgDHNuozWfCCrAeAxLy-j3W7nP3AWtvmntZWnUo_Q@mail.gmail.com> Here's the latest news in docland. Thanks for all the great input at the Summit and excellent follow up conversations on the mailing lists. 1. In review and merged recently: Conversion of the High Availability Guide to DocBook to ease maintenance. It's so interesting that the conversation about the End User Guide and adding Heat Template information has Julien suggesting asciidoc -- we haven't seen an uptick in contributions to the single asciidoc file we had in the repo. But it's an unfair comparison since High Availability is a specialty that not many would have contributed to. So let's keep talking about the priorities for authoring ease. Addition of roadmap.rst to each guide's directory. You can see what tasks are not large enough to merit a blueprint but are still needed work on any given guide. Also note that the <project>-specs repos were rumored to be renamed to <program>-specs, but they are going to remain <project>-specs. I haven't been compelled to create a docs-specs repo and instead went with the roadmap file mentioned above. The database-api repository is now deleted and the API documentation for the trove project now lives in the trove repository. Thanks for the interest and let's keep doing that move for all the projects. 2. High priority doc work: I've re-started an effort to bring in the O'Reilly content with index entries wholesale at https://review.openstack.org/#/c/96015/ - let's merge quickly so that rebasing isn't so difficult and so we can merge in the havana to icehouse upgrade information. The Architecture design guide book sprint is being planned by Ken Hui and we have enough authors as of now but he is wait listing so do contact him if you're interested. The dates are July 7-11 and VMware is hosting in Palo Alto. Still working on persona definitions for the Documentation so that the intended audience can be added to each guide in the front matter. Also we're working on further organizing the Documentation/HowTo wiki page to encourage newcomers. The Security Guide will be moving to its own repository with a separate core review team. Thanks all for the interest there! 3. Doc work going on that I know of: We're continuing discussions about the User Guide to see if we can automate some of the Orchestration reference information and incorporate into the End User Guide or Admin User Guide. Matt is working on writing up standards for file names and xml:ids as part of the install guide work. Follow along at http://lists.openstack.org/pipermail/openstack-docs/2014-May/004471.html. 4. New incoming doc requests: I'd like to get started on app developer documentation and have been talking to various community members from HP and other places. I'm also meeting with Todd Morey, the Foundation designer who originally desiged docs.openstack.org, this week for design ideas for docs. 5. Doc tools updates: The Maven Clouddocs plugin is at 2.0.2 now, and openstack-doc-tools is at 0.15. With 2.0.2 you can use markup within a code listing to emphasize (with bold output) anything you want to highlight in what's returned to the user. There's now a "checklang" non-voting gate test to test translations. When those break, please contact the openstack-docs list. Andreas has file this bug for further investigation and tracking: https://bugs.launchpad.net/ openstack-i18n/+bug/1324007 3:05 AM (5 hours ago) 6. Other doc news: I still want to have the discussion about moving the training guides out of the openstack-manuals repo with a separate core review team similar to the Security Guide. Let me know about good next steps there and we can make a plan. -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140528/39561157/attachment.html> From diane.fleming at RACKSPACE.COM Wed May 28 14:10:14 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Wed, 28 May 2014 14:10:14 +0000 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CAD0KtVEm4pEwP2RVPah20SgjSruALXq9Cpq-imHsThnMrkbUug@mail.gmail.com> Message-ID: <CFAB57AE.2E379%diane.fleming@rackspace.com> That looks good. My only change would be that sections should be section_*, only because that's how most of them are named at the moment so it would save a lot of work to keep what we already have. I have also used created other files for content sharing, such as itemized lists or tables. I usually prefix the file name with the object type in the file. itemizedlist_service_list.xml (for example) table_server_status.xml Oh, and for prefaces, I just use preface.xml Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com From: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>> Date: Wednesday, May 28, 2014 9:04 AM To: Nick Chase <nchase at mirantis.com<mailto:nchase at mirantis.com>> Cc: Andreas Jaeger <aj at suse.com<mailto:aj at suse.com>>, "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>> Subject: Re: [Openstack-docs] Conventions for filenames and chapter/section IDs Here's what I'll update in the Documentation/Conventions page if everyone agrees: For file names, use bk_ ch_ and sec_ at the beginning of the file name to indicate the type of file it is in the hierarchy of the build. For further organization, you can use subdirectories to organize the files by a particular grouping such as project or topic. For xml:id creation, follow these guidelines. - xml:id must be unique across a built deliverable, otherwise you get build errors - xml:id creates the HTML file name so it should be human-readable, not codified like the file name - xml:id should closely follow the actual title in the text, using dashes for spaces - xml:id creation should consider search and find-ability as well as human-readability I prefer not to document the use a processing instruction like <?dbhtml filename="name"> as that should be the rare exception. Thanks, Anne On Mon, May 26, 2014 at 11:13 AM, Nick Chase <nchase at mirantis.com<mailto:nchase at mirantis.com>> wrote: My concern on this is that it raises a barrier to entry for contributors. It's not intuitive. As a fix in an emergency, sure. But I'd be concerned about building this out as the standard way we do things. ---- Nick On Mon, May 26, 2014 at 11:43 AM, David Cramer <david.cramer at rackspace.com<mailto:david.cramer at rackspace.com>> wrote: On 5/26/14, 10:07 AM, Nick Chase wrote: > Plus my concern in changing Id values is breaking any references. You can reduce (but not eliminate) the impact of a file name change by changing the file names via a processing instruction: <section xml:id="some-dumb-id"><?dbhtml filename="intro.html"?>... If you use <?dbhtml filename="..."?> you'll get the aesthetically pleasing intro.html file name without having to change the xml:id and break xrefs to the section. However, if you have external links to some-dumb-id.html from other documents, those links would obviously break. Regardless of the publishing tool chain, when changing the names of existing resources on the web, the best approach is to add 301 redirects to avoid breaking bookmarks, links, and losing SEO karma. Regards, David _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140528/101b742b/attachment-0001.html> From anne at openstack.org Wed May 28 14:20:00 2014 From: anne at openstack.org (Anne Gentle) Date: Wed, 28 May 2014 09:20:00 -0500 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CFAB57AE.2E379%diane.fleming@rackspace.com> References: <CAD0KtVEm4pEwP2RVPah20SgjSruALXq9Cpq-imHsThnMrkbUug@mail.gmail.com> <CFAB57AE.2E379%diane.fleming@rackspace.com> Message-ID: <CAD0KtVFD9RQa6Ct_dnHU8Ly60_+eYWWzoSN5tOx_dYZXO-42CA@mail.gmail.com> On Wed, May 28, 2014 at 9:10 AM, Diane Fleming <diane.fleming at rackspace.com>wrote: > That looks good. > > My only change would be that sections should be section_*, only because > that's how most of them are named at the moment so it would save a lot of > work to keep what we already have. > Ha, oops, I should have known that, sorry. > > I have also used created other files for content sharing, such as > itemized lists or tables. I usually prefix the file name with the object > type in the file. > > itemizedlist_service_list.xml (for example) > table_server_status.xml > > Makes sense. The table_prefix is very helpful. > Oh, and for prefaces, I just use > > preface.xml > > Ok, I'll note in the wiki page. Thanks! > > *Diane* > *----------------------------------------------* > Diane Fleming > Software Developer II - US > diane.fleming at rackspace.com > Cell 512.323.6799 > Office 512.874.1260 > Skype drfleming0227 > Google-plus diane.fleming at gmail.com > > From: Anne Gentle <anne at openstack.org> > Date: Wednesday, May 28, 2014 9:04 AM > > To: Nick Chase <nchase at mirantis.com> > Cc: Andreas Jaeger <aj at suse.com>, "openstack-docs at lists.openstack.org" < > openstack-docs at lists.openstack.org> > Subject: Re: [Openstack-docs] Conventions for filenames and > chapter/section IDs > > Here's what I'll update in the Documentation/Conventions page if > everyone agrees: > > For file names, use bk_ ch_ and sec_ at the beginning of the file name > to indicate the type of file it is in the hierarchy of the build. For > further organization, you can use subdirectories to organize the files by a > particular grouping such as project or topic. > > For xml:id creation, follow these guidelines. > - xml:id must be unique across a built deliverable, otherwise you get > build errors > - xml:id creates the HTML file name so it should be human-readable, not > codified like the file name > - xml:id should closely follow the actual title in the text, using dashes > for spaces > - xml:id creation should consider search and find-ability as well as > human-readability > > I prefer not to document the use a processing instruction like <?dbhtml > filename="name"> as that should be the rare exception. > > Thanks, > Anne > > > On Mon, May 26, 2014 at 11:13 AM, Nick Chase <nchase at mirantis.com> wrote: > >> My concern on this is that it raises a barrier to entry for contributors. >> It's not intuitive. As a fix in an emergency, sure. But I'd be concerned >> about building this out as the standard way we do things. >> >> ---- Nick >> >> >> On Mon, May 26, 2014 at 11:43 AM, David Cramer < >> david.cramer at rackspace.com> wrote: >> >>> On 5/26/14, 10:07 AM, Nick Chase wrote: >>> > Plus my concern in changing Id values is breaking any references. >>> >>> You can reduce (but not eliminate) the impact of a file name change by >>> changing the file names via a processing instruction: >>> >>> <section xml:id="some-dumb-id"><?dbhtml filename="intro.html"?>... >>> >>> If you use <?dbhtml filename="..."?> you'll get the aesthetically >>> pleasing intro.html file name without having to change the xml:id and >>> break xrefs to the section. However, if you have external links to >>> some-dumb-id.html from other documents, those links would obviously >>> break. >>> >>> Regardless of the publishing tool chain, when changing the names of >>> existing resources on the web, the best approach is to add 301 redirects >>> to avoid breaking bookmarks, links, and losing SEO karma. >>> >>> Regards, >>> David >>> >>> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140528/b76bd876/attachment.html> From mkassawara at gmail.com Wed May 28 14:22:04 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Wed, 28 May 2014 08:22:04 -0600 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CAD0KtVFD9RQa6Ct_dnHU8Ly60_+eYWWzoSN5tOx_dYZXO-42CA@mail.gmail.com> References: <CAD0KtVEm4pEwP2RVPah20SgjSruALXq9Cpq-imHsThnMrkbUug@mail.gmail.com> <CFAB57AE.2E379%diane.fleming@rackspace.com> <CAD0KtVFD9RQa6Ct_dnHU8Ly60_+eYWWzoSN5tOx_dYZXO-42CA@mail.gmail.com> Message-ID: <CABA+jQrTf-i=scx86HdT2q0qsU0GaNVsk6qcRq+0WjVvw0RiyQ@mail.gmail.com> +2 from me... thanks everyone! On Wed, May 28, 2014 at 8:20 AM, Anne Gentle <anne at openstack.org> wrote: > > > > On Wed, May 28, 2014 at 9:10 AM, Diane Fleming < > diane.fleming at rackspace.com> wrote: > >> That looks good. >> >> My only change would be that sections should be section_*, only because >> that's how most of them are named at the moment so it would save a lot of >> work to keep what we already have. >> > > Ha, oops, I should have known that, sorry. > > >> >> I have also used created other files for content sharing, such as >> itemized lists or tables. I usually prefix the file name with the object >> type in the file. >> >> > itemizedlist_service_list.xml (for example) >> table_server_status.xml >> >> > Makes sense. The table_prefix is very helpful. > > >> Oh, and for prefaces, I just use >> >> preface.xml >> >> > Ok, I'll note in the wiki page. Thanks! > > >> >> *Diane* >> *----------------------------------------------* >> Diane Fleming >> Software Developer II - US >> diane.fleming at rackspace.com >> Cell 512.323.6799 >> Office 512.874.1260 >> Skype drfleming0227 >> Google-plus diane.fleming at gmail.com >> >> From: Anne Gentle <anne at openstack.org> >> Date: Wednesday, May 28, 2014 9:04 AM >> >> To: Nick Chase <nchase at mirantis.com> >> Cc: Andreas Jaeger <aj at suse.com>, "openstack-docs at lists.openstack.org" < >> openstack-docs at lists.openstack.org> >> Subject: Re: [Openstack-docs] Conventions for filenames and >> chapter/section IDs >> >> Here's what I'll update in the Documentation/Conventions page if >> everyone agrees: >> >> For file names, use bk_ ch_ and sec_ at the beginning of the file name >> to indicate the type of file it is in the hierarchy of the build. For >> further organization, you can use subdirectories to organize the files by a >> particular grouping such as project or topic. >> >> For xml:id creation, follow these guidelines. >> - xml:id must be unique across a built deliverable, otherwise you get >> build errors >> - xml:id creates the HTML file name so it should be human-readable, not >> codified like the file name >> - xml:id should closely follow the actual title in the text, using >> dashes for spaces >> - xml:id creation should consider search and find-ability as well as >> human-readability >> >> I prefer not to document the use a processing instruction like <?dbhtml >> filename="name"> as that should be the rare exception. >> >> Thanks, >> Anne >> >> >> On Mon, May 26, 2014 at 11:13 AM, Nick Chase <nchase at mirantis.com> wrote: >> >>> My concern on this is that it raises a barrier to entry for >>> contributors. It's not intuitive. As a fix in an emergency, sure. But >>> I'd be concerned about building this out as the standard way we do things. >>> >>> ---- Nick >>> >>> >>> On Mon, May 26, 2014 at 11:43 AM, David Cramer < >>> david.cramer at rackspace.com> wrote: >>> >>>> On 5/26/14, 10:07 AM, Nick Chase wrote: >>>> > Plus my concern in changing Id values is breaking any references. >>>> >>>> You can reduce (but not eliminate) the impact of a file name change by >>>> changing the file names via a processing instruction: >>>> >>>> <section xml:id="some-dumb-id"><?dbhtml filename="intro.html"?>... >>>> >>>> If you use <?dbhtml filename="..."?> you'll get the aesthetically >>>> pleasing intro.html file name without having to change the xml:id and >>>> break xrefs to the section. However, if you have external links to >>>> some-dumb-id.html from other documents, those links would obviously >>>> break. >>>> >>>> Regardless of the publishing tool chain, when changing the names of >>>> existing resources on the web, the best approach is to add 301 redirects >>>> to avoid breaking bookmarks, links, and losing SEO karma. >>>> >>>> Regards, >>>> David >>>> >>>> >>> >>> _______________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.openstack.org >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>> >>> >> > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140528/ac336025/attachment-0001.html> From aj at suse.com Wed May 28 16:59:54 2014 From: aj at suse.com (Andreas Jaeger) Date: Wed, 28 May 2014 18:59:54 +0200 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CAD0KtVEm4pEwP2RVPah20SgjSruALXq9Cpq-imHsThnMrkbUug@mail.gmail.com> References: <CABA+jQoKAoy8OUtNNf1bwUK3jCRrYqGRx22NpH_eUuATgD0fig@mail.gmail.com> <CFA8BDF2.2DFA0%diane.fleming@rackspace.com> <CA+p99Gnwea4hT=bo4=W4sTOG4jVXjbi8VrgO8UmkmDx9c_WxuA@mail.gmail.com> <911A41E5F7881A4C8DE8BE32135554A9A1CB8C21@ORD1EXD01.RACKSPACE.CORP> <CA+p99GnUAz0Z+CqzXutLAWkei51JjVp-H84AdYx+s6s_AHvPzA@mail.gmail.com> <CAD0KtVEm4pEwP2RVPah20SgjSruALXq9Cpq-imHsThnMrkbUug@mail.gmail.com> Message-ID: <5386160A.3040808@suse.com> On 05/28/2014 04:04 PM, Anne Gentle wrote: > Here's what I'll update in the Documentation/Conventions page if > everyone agrees: > > For file names, use bk_ ch_ and sec_ at the beginning of the file name > to indicate the type of file it is in the hierarchy of the build. For > further organization, you can use subdirectories to organize the files > by a particular grouping such as project or topic. Agreed (with using section as mentioned as followup) > For xml:id creation, follow these guidelines. > - xml:id must be unique across a built deliverable, otherwise you get > build errors > - xml:id creates the HTML file name so it should be human-readable, not > codified like the file name > - xml:id should closely follow the actual title in the text, using > dashes for spaces I normally use underscores for spaces. > - xml:id creation should consider search and find-ability as well as > human-readability > > I prefer not to document the use a processing instruction like <?dbhtml > filename="name"> as that should be the rare exception. > Agreed, thanks, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Wed May 28 17:13:18 2014 From: anne at openstack.org (Anne Gentle) Date: Wed, 28 May 2014 12:13:18 -0500 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <5386160A.3040808@suse.com> References: <CABA+jQoKAoy8OUtNNf1bwUK3jCRrYqGRx22NpH_eUuATgD0fig@mail.gmail.com> <CFA8BDF2.2DFA0%diane.fleming@rackspace.com> <CA+p99Gnwea4hT=bo4=W4sTOG4jVXjbi8VrgO8UmkmDx9c_WxuA@mail.gmail.com> <911A41E5F7881A4C8DE8BE32135554A9A1CB8C21@ORD1EXD01.RACKSPACE.CORP> <CA+p99GnUAz0Z+CqzXutLAWkei51JjVp-H84AdYx+s6s_AHvPzA@mail.gmail.com> <CAD0KtVEm4pEwP2RVPah20SgjSruALXq9Cpq-imHsThnMrkbUug@mail.gmail.com> <5386160A.3040808@suse.com> Message-ID: <CAD0KtVEffxEvV0Y3R8SorzXr558jptdzjbmAFyPp2CoEiaEYrA@mail.gmail.com> On Wed, May 28, 2014 at 11:59 AM, Andreas Jaeger <aj at suse.com> wrote: > On 05/28/2014 04:04 PM, Anne Gentle wrote: > > Here's what I'll update in the Documentation/Conventions page if > > everyone agrees: > > > > For file names, use bk_ ch_ and sec_ at the beginning of the file name > > to indicate the type of file it is in the hierarchy of the build. For > > further organization, you can use subdirectories to organize the files > > by a particular grouping such as project or topic. > > Agreed (with using section as mentioned as followup) > > > For xml:id creation, follow these guidelines. > > - xml:id must be unique across a built deliverable, otherwise you get > > build errors > > - xml:id creates the HTML file name so it should be human-readable, not > > codified like the file name > > - xml:id should closely follow the actual title in the text, using > > dashes for spaces > > I normally use underscores for spaces. > Ah, okay. I was thinking of Drupal/Wordpress convention and wondering if one is preferred over the other for search optimization, anyone know? > > > - xml:id creation should consider search and find-ability as well as > > human-readability > > > > I prefer not to document the use a processing instruction like <?dbhtml > > filename="name"> as that should be the rare exception. > > > > Agreed, thanks, > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140528/bc01b895/attachment.html> From mkassawara at gmail.com Wed May 28 23:55:11 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Wed, 28 May 2014 17:55:11 -0600 Subject: [Openstack-docs] Use of itemized lists in Ops Guide upgrade chapter Message-ID: <CABA+jQreES2pUZFZzUBgc0X0VUZeHy_C4FM+bW604DG=jx-eDA@mail.gmail.com> Can anyone tell me why the Ops Guide upgrade chapter uses itemized lists? If possible, I would like to use procedures to improve structure and readability. -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140528/6313678c/attachment.html> From anne at openstack.org Thu May 29 00:59:09 2014 From: anne at openstack.org (Anne Gentle) Date: Wed, 28 May 2014 19:59:09 -0500 Subject: [Openstack-docs] Use of itemized lists in Ops Guide upgrade chapter In-Reply-To: <CABA+jQreES2pUZFZzUBgc0X0VUZeHy_C4FM+bW604DG=jx-eDA@mail.gmail.com> References: <CABA+jQreES2pUZFZzUBgc0X0VUZeHy_C4FM+bW604DG=jx-eDA@mail.gmail.com> Message-ID: <CAD0KtVEszJn7cT_azosXV6AsoQ-eu+0_-HZPtypf8rAHcEJtkw@mail.gmail.com> Some of this is a judgement call due to the way it's written in sections with a step or two for each section. For the generalized listing of steps, those should remain lists. These sections could possibly be converted to procedures, but I'll try to explain why it might not be a good idea for each: - Perform a Backup (this is just two steps, First and Next so likely the judgement call was not to use procedure) - Update Configuration Files (there are a lot of "if" statements in this, I'm not sure how markup goes for optional steps, so likely they decided not to mark up with procedure since it's quite general) - Cleaning Up and Final Configuration File Updates (honestly, I can see why this also is not a procedure because it's not step-by-step, it's generalized guidance) Really, I think leave it alone, there is probably higher-value work to do than changing the markup there. Your testing has been super valuable and is the real value for that documentation. Anne On Wed, May 28, 2014 at 6:55 PM, Matt Kassawara <mkassawara at gmail.com>wrote: > Can anyone tell me why the Ops Guide upgrade chapter uses itemized lists? > If possible, I would like to use procedures to improve structure and > readability. > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140528/f16d87df/attachment.html> From mkassawara at gmail.com Thu May 29 01:06:30 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Wed, 28 May 2014 19:06:30 -0600 Subject: [Openstack-docs] Use of itemized lists in Ops Guide upgrade chapter In-Reply-To: <CAD0KtVEszJn7cT_azosXV6AsoQ-eu+0_-HZPtypf8rAHcEJtkw@mail.gmail.com> References: <CABA+jQreES2pUZFZzUBgc0X0VUZeHy_C4FM+bW604DG=jx-eDA@mail.gmail.com> <CAD0KtVEszJn7cT_azosXV6AsoQ-eu+0_-HZPtypf8rAHcEJtkw@mail.gmail.com> Message-ID: <CABA+jQrXGPyOOwZCcQjvqf3okrLD7QDgkQGFrxDZMCUx7t2kpA@mail.gmail.com> Alright... I'll upload my patch using the existing markup and see what happens during the review process. On Wed, May 28, 2014 at 6:59 PM, Anne Gentle <anne at openstack.org> wrote: > Some of this is a judgement call due to the way it's written in sections > with a step or two for each section. For the generalized listing of steps, > those should remain lists. > > These sections could possibly be converted to procedures, but I'll try to > explain why it might not be a good idea for each: > > - Perform a Backup (this is just two steps, First and Next so likely the > judgement call was not to use procedure) > - Update Configuration Files (there are a lot of "if" statements in this, > I'm not sure how markup goes for optional steps, so likely they decided not > to mark up with procedure since it's quite general) > - Cleaning Up and Final Configuration File Updates (honestly, I can see > why this also is not a procedure because it's not step-by-step, it's > generalized guidance) > > Really, I think leave it alone, there is probably higher-value work to do > than changing the markup there. Your testing has been super valuable and is > the real value for that documentation. > Anne > > > > > > On Wed, May 28, 2014 at 6:55 PM, Matt Kassawara <mkassawara at gmail.com>wrote: > >> Can anyone tell me why the Ops Guide upgrade chapter uses itemized lists? >> If possible, I would like to use procedures to improve structure and >> readability. >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140528/16dcd960/attachment.html> From tom at openstack.org Thu May 29 02:56:34 2014 From: tom at openstack.org (Tom Fifield) Date: Thu, 29 May 2014 10:56:34 +0800 Subject: [Openstack-docs] Training Guides becoming a project in its own right? Message-ID: <5386A1E2.80807@openstack.org> Hi, Sean Roberts, Stefano and I just had a very fruitful discussion regarding the training manuals project. We think that it's time to allow the the training guides to become a free-standing project of its own accord, and start attracting significantly more people around it. This will make it easier for contributors who just want to work on training to find the project, see lists of bugs and tasks relevant to them*, and also provide a clearer pathway toward becoming contributors, and eventually core reviewers. It will also enable the training guides project to have its own policies, and allow the repository to be used for investigation of training infrastructure, such as the recent forays into moodle for example. However, with every change such as this, there are drawbacks, and so we feel it's important to discuss these as well - and most importantly get your input. For example, while we can continue to re-use tools and content, this would mean a different review queue and repository - which could frustrate if you are working across both projects. What are your thoughts? Regards, Tom * as opposed to the 400 odd in the openstack-manuals tracker! From frans at meruvian.org Thu May 29 03:12:00 2014 From: frans at meruvian.org (Frans Thamura) Date: Thu, 29 May 2014 10:12:00 +0700 Subject: [Openstack-docs] Training Guides becoming a project in its own right? In-Reply-To: <5386A1E2.80807@openstack.org> References: <5386A1E2.80807@openstack.org> Message-ID: <CAOeeQyp9mz7wasNom516-GA0aVBgKXURTenk1WLO=CmscTzfDA@mail.gmail.com> +1 I love part of it. F On May 29, 2014 9:56 AM, "Tom Fifield" <tom at openstack.org> wrote: > Hi, > > Sean Roberts, Stefano and I just had a very fruitful discussion regarding > the training manuals project. > > We think that it's time to allow the the training guides to become a > free-standing project of its own accord, and start attracting significantly > more people around it. > > This will make it easier for contributors who just want to work on > training to find the project, see lists of bugs and tasks relevant to > them*, and also provide a clearer pathway toward becoming contributors, and > eventually core reviewers. > > It will also enable the training guides project to have its own policies, > and allow the repository to be used for investigation of training > infrastructure, such as the recent forays into moodle for example. > > However, with every change such as this, there are drawbacks, and so we > feel it's important to discuss these as well - and most importantly get > your input. > > For example, while we can continue to re-use tools and content, this would > mean a different review queue and repository - which could frustrate if you > are working across both projects. > > What are your thoughts? > > > Regards, > > > > Tom > > > * as opposed to the 400 odd in the openstack-manuals tracker! > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140529/073f7580/attachment.html> From gauvain.pocentek at objectif-libre.com Thu May 29 09:14:09 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Thu, 29 May 2014 11:14:09 +0200 Subject: [Openstack-docs] [openstack-dev] [Heat][Documentation] Heat template documentation In-Reply-To: <0ffd733cc476e5b3ed39bb5be83bd5f7@objectif-libre.com> References: <CAD0KtVF6qnO4-Kd7ELxJZU53r7jtTSv7mCJG3ZVyJu-C+LxtYA@mail.gmail.com> <37903930f5456fa6f09066fe41cce960@objectif-libre.com> <CADb+p3RJ=cO0BxRsp7p=QiScS72dg5+ruz4WFZS9ZqyjE3sYcA@mail.gmail.com> <537BE872.3090509@redhat.com> <CAD0KtVHiqMgEq-A3ozq2ZVx3PtAZ=jwUnWHfa=pht5WXnLMHtA@mail.gmail.com> <537E6B94.1090806@redhat.com> <20140523101315.GA22280@t430slt.redhat.com> <537F2530.8010905@suse.com> <20140523111957.GB22280@t430slt.redhat.com> <CAD0KtVHP_=Og1uyL_p_k0+5nSk-8mJHFtOPbXqu-mO8R7QXg8Q@mail.gmail.com> <20140523134251.GC22280@t430slt.redhat.com> <CAD0KtVEyJmezeHhQqZXBwUwS9-cbafYp9sCcEp=ybiWuiKtUzw@mail.gmail.com> <f27ea5d694bbb2f800575c22266f0d39@objectif-libre.com> <53853639.2020506@redhat.com> <0ffd733cc476e5b3ed39bb5be83bd5f7@objectif-libre.com> Message-ID: <41416605e3d36f84d9013f029ba22765@objectif-libre.com> Le 2014-05-28 07:17, Gauvain Pocentek a ?crit?: > Le 2014-05-28 03:04, Steve Baker a ?crit?: >> On 28/05/14 03:15, Gauvain Pocentek wrote: >>> Le 2014-05-23 15:57, Anne Gentle a ?crit : >>>> On Fri, May 23, 2014 at 8:42 AM, Steven Hardy <shardy at redhat.com> >>>> wrote: >>>> >>>>> On Fri, May 23, 2014 at 08:09:06AM -0500, Anne Gentle wrote: >>>>>> On Fri, May 23, 2014 at 6:19 AM, Steven Hardy <shardy at redhat.com> >>>>>> wrote: >>>>>> >>>>>>> On Fri, May 23, 2014 at 12:38:40PM +0200, Andreas Jaeger wrote: >>>>>>>> On 05/23/2014 12:13 PM, Steven Hardy wrote: >>>>>>>>> [...] >>>>>>>>> I'll hold my hand up as one developer who tried to contribute >>>>>>>>> but ran >>>>>>> away >>>>>>>>> screaming due to all the XML-java-ness of the current process. >>>>>>>>> I don't think markup complexity is a major barrier to >>>>>>>>> contribution. >>>>>>> Needing >>>>>>>>> to use a closed source editor and download unfathomably huge >>>>>>>>> amounts of >>>>>>>>> java to build locally definitely are though IMO/IME. >>>>>>>> You do not need a closed sourced editor for XML - I'm using >>>>>>>> emacs >>>>>>>> and >>>>>>>> others in the team use vi for it. >>>>>>> Sure, maybe "need" was the wrong word to use, my apologies. >>>>>>> Regardless, >>>>>>> the docs refer to a closed source tool being "encouraged", which >>>>>>> immediately discouraged me when trying to figure out the >>>>>>> workflow. >>>>>>> I've tried editing XML in vim a few times, and although it's >>>>>>> obviously >>>>>>> possible, it's far less painful when I'm dealing with other more >>>>>>> human-friendly formats. >>>>>>> >>>>>>>> Yes, it downloads a lot Java once. We also now build the >>>>>>>> documents as >>>>>>>> part of the gate, so you can also check changes by clicking the >>>>>>>> "checkbuild" target, it will show you the converted books, >>>>>>> Sure, that's good, but my (and I'd guess many others) preference >>>>>>> is for >>>>>>> formats which can be easily built locally with only >>>>>>> distro-provided tools, >>>>>>> not a huge pile of third party java. >>>>>>> Not trying to start a format-advocacy argument here, just trying >>>>>>> to provide >>>>>>> a data-point that, if the success criteria is developer >>>>>>> participation in >>>>>>> the docs process, then the current toolchain is definitely a >>>>>>> barrier to >>>>>>> participation for some potential contributors. >>>>>>> >>>>>> Thanks for the discussions -- let's keep a tone of civility. >>>>>> Understand >>>>>> that doc writers have specific tools that work well for them. >>>>>> That >>>>>> said, we >>>>>> do want to collaborate more with our end users specifically. >>>>> My apologies if my remarks have been interpreted as uncivil, that >>>>> was >>>>> definitely not my intention. >>>> Oh no not at all, sorry -- my intent is that we are all staying >>>> civil >>>> and it's good. :) >>>> >>>> >>>>> The only point I really wanted to convey was +1 on trying out an >>>>> easier >>>>> markup, and thanks for bringing up the topic of a user orientated >>>>> orchestration guide - I would definitely like to contribute to the >>>>> effort. >>>> So we're still a little stuck on the tradeoffs -- with easier >>>> markup >>>> we lose some features. >>>> For other generated reference docs, we maintain a set of python >>>> scripts in openstack-doc-tools. Is it possible for someone to look >>>> into generating the Heat template reference information outside of >>>> Sphinx? >>> Yes, I can look into that. >>> The idea would be to generate some docbook from RST... So why not do >>> it for the whole to-be-written heat user guide in that case? >>> What I get from this thread is that 1) docbook is the best format to >>> use to generate a nice and feature-rich output, 2) developers don't >>> want to write docbook. Without being able to handle a different >>> format >>> developers will no contribute, which is bad because they want, and >>> we >>> want them to contribute :) >>> So my feeling is that we should work on the tools to convert RST (or >>> whatever format, but RST seems to be the "norm" for openstack >>> projects) to docbook, and generate our online documentation from >>> there. There are tools that can help us doing that, and I don't see >>> an >>> other solution that would make us move forward. >>> Anne, you talked about experimenting with the end user guide, and >>> after the discussion and the technical info brought by Doug, Steve >>> and >>> Steven, I now think it is worth trying. >>> >> In this vein, I enabled the sphinx xml builder in heat: >> https://review.openstack.org/#/c/95979/ >> And here is a sample of the output: >> http://paste.openstack.org/show/81811/ >> http://paste.openstack.org/show/81812/ >> This looks like it could be readily transformed into DocBook via XSL. > > http://ebellot.chez.com/dn2dbk/index.htm could be used as a starting > point. It generates docbook 4, but can probably be easily modified to > generate docbook 5, adapted to our conventions. The doc is in french, > if anyone's interested I can do a quick translation of the important > parts. The result of my tests: http://pocentek.net/~gauvain/heat-template-guide/content/ I used the XML generated by 'sphinx-build xml' as source, with this resources.py patch: https://review.openstack.org/96398 There are a few things manually setup (pom.xml, and the master structure of the docbook XML), but I think that they could be automated. I also used a few sed commands, mainly to handle xml IDs. It might be possible to handle this with xslt, but using sed was a faster solution. You can get the code: git clone http://pocentek.net/~gauvain/heat-template-guide/poc-rst2docbook There's room for improvement, and we should test more advanced RST markup, but I think that this solution could really work for the user guide. Gauvain From harry.sutton at hp.com Thu May 29 12:20:32 2014 From: harry.sutton at hp.com (Sutton, Harry (Converged Systems & Solutions ERT)) Date: Thu, 29 May 2014 08:20:32 -0400 Subject: [Openstack-docs] Training Guides becoming a project in its own right? In-Reply-To: <5386A1E2.80807@openstack.org> References: <5386A1E2.80807@openstack.org> Message-ID: <53872610.5090302@hp.com> I'm in favor of this - I'd like to get more involved in this effort, and having it as a separate project might simplify that process. /Harry On 05/28/2014 10:56 PM, Tom Fifield wrote: > Hi, > > Sean Roberts, Stefano and I just had a very fruitful discussion > regarding the training manuals project. > > We think that it's time to allow the the training guides to become a > free-standing project of its own accord, and start attracting > significantly more people around it. > > This will make it easier for contributors who just want to work on > training to find the project, see lists of bugs and tasks relevant to > them*, and also provide a clearer pathway toward becoming > contributors, and eventually core reviewers. > > It will also enable the training guides project to have its own > policies, and allow the repository to be used for investigation of > training infrastructure, such as the recent forays into moodle for > example. > > However, with every change such as this, there are drawbacks, and so > we feel it's important to discuss these as well - and most importantly > get your input. > > For example, while we can continue to re-use tools and content, this > would mean a different review queue and repository - which could > frustrate if you are working across both projects. > > What are your thoughts? > > > Regards, > > > > Tom > > > * as opposed to the 400 odd in the openstack-manuals tracker! > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- A non-text attachment was scrubbed... Name: smime.p7s Type: application/pkcs7-signature Size: 5079 bytes Desc: S/MIME Cryptographic Signature URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140529/e7249cf4/attachment.bin> From frans at meruvian.org Thu May 29 12:24:07 2014 From: frans at meruvian.org (Frans Thamura) Date: Thu, 29 May 2014 19:24:07 +0700 Subject: [Openstack-docs] Training Guides becoming a project in its own right? In-Reply-To: <53872610.5090302@hp.com> References: <5386A1E2.80807@openstack.org> <53872610.5090302@hp.com> Message-ID: <CAOeeQypOjk_LM-x9qctfqawvXaKmt0d6t9XMi_-n9ao0t2dP4g@mail.gmail.com> Any mechanism regarding this work? Esp.hard to get what going on in sfbay hackathon, which i am interest to create smiliar here in indonesia. The tutorial is amazing comperehensive, and we can see all distro tutorial pooled in openstack.org, this is awesome rather visiting every web of distro like ubuntu or centos . So when we can work? F On May 29, 2014 7:20 PM, "Sutton, Harry (Converged Systems & Solutions ERT)" <harry.sutton at hp.com> wrote: > I'm in favor of this - I'd like to get more involved in this effort, and > having it as a separate project might simplify that process. > > /Harry > > On 05/28/2014 10:56 PM, Tom Fifield wrote: > >> Hi, >> >> Sean Roberts, Stefano and I just had a very fruitful discussion regarding >> the training manuals project. >> >> We think that it's time to allow the the training guides to become a >> free-standing project of its own accord, and start attracting significantly >> more people around it. >> >> This will make it easier for contributors who just want to work on >> training to find the project, see lists of bugs and tasks relevant to >> them*, and also provide a clearer pathway toward becoming contributors, and >> eventually core reviewers. >> >> It will also enable the training guides project to have its own policies, >> and allow the repository to be used for investigation of training >> infrastructure, such as the recent forays into moodle for example. >> >> However, with every change such as this, there are drawbacks, and so we >> feel it's important to discuss these as well - and most importantly get >> your input. >> >> For example, while we can continue to re-use tools and content, this >> would mean a different review queue and repository - which could frustrate >> if you are working across both projects. >> >> What are your thoughts? >> >> >> Regards, >> >> >> >> Tom >> >> >> * as opposed to the 400 odd in the openstack-manuals tracker! >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140529/46e6a9da/attachment.html> From aj at suse.com Thu May 29 13:30:31 2014 From: aj at suse.com (Andreas Jaeger) Date: Thu, 29 May 2014 15:30:31 +0200 Subject: [Openstack-docs] Training Guides becoming a project in its own right? In-Reply-To: <5386A1E2.80807@openstack.org> References: <5386A1E2.80807@openstack.org> Message-ID: <53873677.1070107@suse.com> On 05/29/2014 04:56 AM, Tom Fifield wrote: > Hi, > > Sean Roberts, Stefano and I just had a very fruitful discussion > regarding the training manuals project. > > We think that it's time to allow the the training guides to become a > free-standing project of its own accord, and start attracting > significantly more people around it. > > This will make it easier for contributors who just want to work on > training to find the project, see lists of bugs and tasks relevant to > them*, and also provide a clearer pathway toward becoming contributors, > and eventually core reviewers. > > It will also enable the training guides project to have its own > policies, and allow the repository to be used for investigation of > training infrastructure, such as the recent forays into moodle for example. > > However, with every change such as this, there are drawbacks, and so we > feel it's important to discuss these as well - and most importantly get > your input. > > For example, while we can continue to re-use tools and content, this > would mean a different review queue and repository - which could > frustrate if you are working across both projects. > > What are your thoughts? I hope this will revive the training guide, it really needs a dedicated team that works on it to improve the quality and accuracy. I propose that the training guides team - even in its own project - works together with the documentation team to share tools and styles. There shouldn't be two different sets of conventions for writing... Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Thu May 29 13:32:47 2014 From: aj at suse.com (Andreas Jaeger) Date: Thu, 29 May 2014 15:32:47 +0200 Subject: [Openstack-docs] Training Guides becoming a project in its own right? In-Reply-To: <CAOeeQypOjk_LM-x9qctfqawvXaKmt0d6t9XMi_-n9ao0t2dP4g@mail.gmail.com> References: <5386A1E2.80807@openstack.org> <53872610.5090302@hp.com> <CAOeeQypOjk_LM-x9qctfqawvXaKmt0d6t9XMi_-n9ao0t2dP4g@mail.gmail.com> Message-ID: <538736FF.9060203@suse.com> On 05/29/2014 02:24 PM, Frans Thamura wrote: > Any mechanism regarding this work? > > Esp.hard to get what going on in sfbay hackathon, which i am interest to > create smiliar here in indonesia. > > The tutorial is amazing comperehensive, and we can see all distro > tutorial pooled in openstack.org <http://openstack.org>, this is awesome > rather visiting every web of distro like ubuntu or centos . > > So when we can work? You can already *today* work on the training guides, contribution is welcome! Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Thu May 29 14:49:51 2014 From: aj at suse.com (Andreas Jaeger) Date: Thu, 29 May 2014 16:49:51 +0200 Subject: [Openstack-docs] New localized doc web pages Message-ID: <5387490F.80304@suse.com> The API Quick Start has been translated to French, German, Japanese and Spanish! We now have German and French index pages: http://docs.openstack.org/de/ http://docs.openstack.org/fr/ (proposed - see https://review.openstack.org/96444) For all the guides that are not mentioned on a specific page, we now have a "secret" page which is not reachable from the main index pages: http://docs.openstack.org/draft-i18n-manuals.html It lists all the other guides that are currently built. That way translation teams can easily verify their manuals. If you like to move one of them to "official" pages, feel free to send a patch! Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From berendt at b1-systems.de Thu May 29 14:51:41 2014 From: berendt at b1-systems.de (Christian Berendt) Date: Thu, 29 May 2014 16:51:41 +0200 Subject: [Openstack-docs] Training Guides becoming a project in its own right? In-Reply-To: <5386A1E2.80807@openstack.org> References: <5386A1E2.80807@openstack.org> Message-ID: <5387497D.6030202@b1-systems.de> On 05/29/2014 04:56 AM, Tom Fifield wrote: > What are your thoughts? +1 It's a really good idea to move the training guide into a separate repository. Christian. -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 From anne at openstack.org Thu May 29 17:40:38 2014 From: anne at openstack.org (Anne Gentle) Date: Thu, 29 May 2014 12:40:38 -0500 Subject: [Openstack-docs] Training Guides becoming a project in its own right? In-Reply-To: <5386A1E2.80807@openstack.org> References: <5386A1E2.80807@openstack.org> Message-ID: <CAD0KtVGB2h0W1VzQ9wV4iH8ai5OfkzLwe4+J5pa+BkWxNq5Jig@mail.gmail.com> On Wed, May 28, 2014 at 9:56 PM, Tom Fifield <tom at openstack.org> wrote: > Hi, > > Sean Roberts, Stefano and I just had a very fruitful discussion regarding > the training manuals project. > Thanks you all for discussing. > > We think that it's time to allow the the training guides to become a > free-standing project of its own accord, and start attracting significantly > more people around it. > > This will make it easier for contributors who just want to work on > training to find the project, see lists of bugs and tasks relevant to > them*, and also provide a clearer pathway toward becoming contributors, and > eventually core reviewers. > > It will also enable the training guides project to have its own policies, > and allow the repository to be used for investigation of training > infrastructure, such as the recent forays into moodle for example. > > However, with every change such as this, there are drawbacks, and so we > feel it's important to discuss these as well - and most importantly get > your input. > > For example, while we can continue to re-use tools and content, this would > mean a different review queue and repository - which could frustrate if you > are working across both projects. > I hope the intention is to continue to use inclusion of known tested content from the various other OpenStack repos as needed. > > What are your thoughts? > Sounds great to me. Thanks all! Anne > > > Regards, > > > > Tom > > > * as opposed to the 400 odd in the openstack-manuals tracker! > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140529/5e2375bb/attachment.html> From anne at openstack.org Thu May 29 17:42:57 2014 From: anne at openstack.org (Anne Gentle) Date: Thu, 29 May 2014 12:42:57 -0500 Subject: [Openstack-docs] Anne out 5/30-6/9 Message-ID: <CAD0KtVHOmD7NMm=w_hP7q6rdGA3_fTdU=RiAXWsgtnPWOh5cHQ@mail.gmail.com> I'm taking vacation with the family and have no intentions of paying attention here for about a week. Don't throw any big parties without me. :) Thanks, Anne -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140529/9e6a0739/attachment.html> From mkassawara at gmail.com Thu May 29 17:47:53 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Thu, 29 May 2014 11:47:53 -0600 Subject: [Openstack-docs] Anne out 5/30-6/9 In-Reply-To: <CAD0KtVHOmD7NMm=w_hP7q6rdGA3_fTdU=RiAXWsgtnPWOh5cHQ@mail.gmail.com> References: <CAD0KtVHOmD7NMm=w_hP7q6rdGA3_fTdU=RiAXWsgtnPWOh5cHQ@mail.gmail.com> Message-ID: <CABA+jQpR_JFMUT1ncZVOuHzijpzwYLGFAs-gon+wap41ZUXmXw@mail.gmail.com> We'll just +2 and approve every patch while you're out. Hope you have a great time! On Thu, May 29, 2014 at 11:42 AM, Anne Gentle <anne at openstack.org> wrote: > I'm taking vacation with the family and have no intentions of paying > attention here for about a week. Don't throw any big parties without me. :) > Thanks, > Anne > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140529/ec0d1f78/attachment.html> From aj at suse.com Thu May 29 19:12:22 2014 From: aj at suse.com (Andreas Jaeger) Date: Thu, 29 May 2014 21:12:22 +0200 Subject: [Openstack-docs] Training Guide freeze? Message-ID: <53878696.80405@suse.com> Tom, seeing your patch https://review.openstack.org/#/c/96334/4, I propose that we freeze the training guide for its transition now. This means we're not changing any files below doc/training-guides. Correct? Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From openstack at lanabrindley.com Thu May 29 23:56:45 2014 From: openstack at lanabrindley.com (Lana Brindley) Date: Fri, 30 May 2014 09:56:45 +1000 Subject: [Openstack-docs] Anne out 5/30-6/9 In-Reply-To: <CABA+jQpR_JFMUT1ncZVOuHzijpzwYLGFAs-gon+wap41ZUXmXw@mail.gmail.com> References: <CAD0KtVHOmD7NMm=w_hP7q6rdGA3_fTdU=RiAXWsgtnPWOh5cHQ@mail.gmail.com> <CABA+jQpR_JFMUT1ncZVOuHzijpzwYLGFAs-gon+wap41ZUXmXw@mail.gmail.com> Message-ID: <5387C93D.6030903@lanabrindley.com> It's a +2 party! Have a great vacation, Anne :) L On 30/05/14 03:47, Matt Kassawara wrote: > We'll just +2 and approve every patch while you're out. Hope you have a > great time! > > > On Thu, May 29, 2014 at 11:42 AM, Anne Gentle <anne at openstack.org > <mailto:anne at openstack.org>> wrote: > > I'm taking vacation with the family and have no intentions of paying > attention here for about a week. Don't throw any big parties without > me. :) > Thanks, > Anne > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > <mailto:Openstack-docs at lists.openstack.org> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -- Lana Brindley Technical Writer Rackspace Cloud Builders Australia http://lanabrindley.com From diane.fleming at RACKSPACE.COM Fri May 30 00:49:45 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Fri, 30 May 2014 00:49:45 +0000 Subject: [Openstack-docs] Anne out 5/30-6/9 In-Reply-To: <5387C93D.6030903@lanabrindley.com> References: <CAD0KtVHOmD7NMm=w_hP7q6rdGA3_fTdU=RiAXWsgtnPWOh5cHQ@mail.gmail.com> <CABA+jQpR_JFMUT1ncZVOuHzijpzwYLGFAs-gon+wap41ZUXmXw@mail.gmail.com>, <5387C93D.6030903@lanabrindley.com> Message-ID: <24804B9A-A028-4FCF-8001-84BE6EAF5F3B@RACKSPACE.COM> 2 plus 2 is 4, i've heard. Ann, leave your computer at home!! Sent from my iPhone > On May 29, 2014, at 6:58 PM, "Lana Brindley" <openstack at lanabrindley.com> wrote: > > It's a +2 party! > > Have a great vacation, Anne :) > > L > >> On 30/05/14 03:47, Matt Kassawara wrote: >> We'll just +2 and approve every patch while you're out. Hope you have a >> great time! >> >> >> On Thu, May 29, 2014 at 11:42 AM, Anne Gentle <anne at openstack.org >> <mailto:anne at openstack.org>> wrote: >> >> I'm taking vacation with the family and have no intentions of paying >> attention here for about a week. Don't throw any big parties without >> me. :) >> Thanks, >> Anne >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> <mailto:Openstack-docs at lists.openstack.org> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> >> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > > -- > Lana Brindley > Technical Writer > Rackspace Cloud Builders Australia > http://lanabrindley.com > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs From tom at openstack.org Fri May 30 01:14:34 2014 From: tom at openstack.org (Tom Fifield) Date: Fri, 30 May 2014 09:14:34 +0800 Subject: [Openstack-docs] Training Guides becoming a project in its own right? In-Reply-To: <CAD0KtVGB2h0W1VzQ9wV4iH8ai5OfkzLwe4+J5pa+BkWxNq5Jig@mail.gmail.com> References: <5386A1E2.80807@openstack.org> <CAD0KtVGB2h0W1VzQ9wV4iH8ai5OfkzLwe4+J5pa+BkWxNq5Jig@mail.gmail.com> Message-ID: <5387DB7A.5070502@openstack.org> On 30/05/14 01:40, Anne Gentle wrote: > > > > On Wed, May 28, 2014 at 9:56 PM, Tom Fifield <tom at openstack.org > <mailto:tom at openstack.org>> wrote: > > Hi, > > Sean Roberts, Stefano and I just had a very fruitful discussion > regarding the training manuals project. > > > Thanks you all for discussing. > > > We think that it's time to allow the the training guides to become a > free-standing project of its own accord, and start attracting > significantly more people around it. > > > This will make it easier for contributors who just want to work on > training to find the project, see lists of bugs and tasks relevant > to them*, and also provide a clearer pathway toward becoming > contributors, and eventually core reviewers. > > It will also enable the training guides project to have its own > policies, and allow the repository to be used for investigation of > training infrastructure, such as the recent forays into moodle for > example. > > However, with every change such as this, there are drawbacks, and so > we feel it's important to discuss these as well - and most > importantly get your input. > > For example, while we can continue to re-use tools and content, this > would mean a different review queue and repository - which could > frustrate if you are working across both projects. > > > I hope the intention is to continue to use inclusion of known tested > content from the various other OpenStack repos as needed. Yup, that's the case. > > What are your thoughts? > > > Sounds great to me. Thanks all! > Anne > > > > Regards, > > > > Tom > > > * as opposed to the 400 odd in the openstack-manuals tracker! > > _________________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org> > http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs > <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> > > From mkassawara at gmail.com Fri May 30 01:31:08 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Thu, 29 May 2014 19:31:08 -0600 Subject: [Openstack-docs] Anne out 5/30-6/9 In-Reply-To: <24804B9A-A028-4FCF-8001-84BE6EAF5F3B@RACKSPACE.COM> References: <CAD0KtVHOmD7NMm=w_hP7q6rdGA3_fTdU=RiAXWsgtnPWOh5cHQ@mail.gmail.com> <CABA+jQpR_JFMUT1ncZVOuHzijpzwYLGFAs-gon+wap41ZUXmXw@mail.gmail.com> <5387C93D.6030903@lanabrindley.com> <24804B9A-A028-4FCF-8001-84BE6EAF5F3B@RACKSPACE.COM> Message-ID: <CABA+jQo8Pz=n_eDftk2zdDNzuEdzALLoO3WnmJEuTLgnZEdrqA@mail.gmail.com> Or 2 plus 2 is 5 for extremely high values of 2. :) On Thu, May 29, 2014 at 6:49 PM, Diane Fleming <diane.fleming at rackspace.com> wrote: > 2 plus 2 is 4, i've heard. Ann, leave your computer at home!! > > Sent from my iPhone > > > On May 29, 2014, at 6:58 PM, "Lana Brindley" <openstack at lanabrindley.com> > wrote: > > > > It's a +2 party! > > > > Have a great vacation, Anne :) > > > > L > > > >> On 30/05/14 03:47, Matt Kassawara wrote: > >> We'll just +2 and approve every patch while you're out. Hope you have a > >> great time! > >> > >> > >> On Thu, May 29, 2014 at 11:42 AM, Anne Gentle <anne at openstack.org > >> <mailto:anne at openstack.org>> wrote: > >> > >> I'm taking vacation with the family and have no intentions of paying > >> attention here for about a week. Don't throw any big parties without > >> me. :) > >> Thanks, > >> Anne > >> > >> _______________________________________________ > >> Openstack-docs mailing list > >> Openstack-docs at lists.openstack.org > >> <mailto:Openstack-docs at lists.openstack.org> > >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > >> > >> > >> > >> > >> _______________________________________________ > >> Openstack-docs mailing list > >> Openstack-docs at lists.openstack.org > >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > > > > > -- > > Lana Brindley > > Technical Writer > > Rackspace Cloud Builders Australia > > http://lanabrindley.com > > > > _______________________________________________ > > Openstack-docs mailing list > > Openstack-docs at lists.openstack.org > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140529/c1136058/attachment-0001.html> From guoyingc at cn.ibm.com Fri May 30 02:22:49 2014 From: guoyingc at cn.ibm.com (Ying Chun Guo) Date: Fri, 30 May 2014 10:22:49 +0800 Subject: [Openstack-docs] [Openstack-i18n] New localized doc web pages In-Reply-To: <5387490F.80304@suse.com> References: <5387490F.80304@suse.com> Message-ID: <OFD71DFDDC.1852867E-ON48257CE8.000CFFBC-48257CE8.000D2E66@cn.ibm.com> Thanks, Andreas. How to add documents to the secret page then? Best regards Ying Chun Guo (Daisy) Andreas Jaeger <aj at suse.com> wrote on 2014/05/29 22:49:51: > Andreas Jaeger <aj at suse.com> > 2014/05/29 22:49 > > To > > "openstack-docs at lists.openstack.org" <openstack- > docs at lists.openstack.org>, "openstack-i18n at lists.openstack.org" > <openstack-i18n at lists.openstack.org>, > > cc > > Subject > > [Openstack-i18n] New localized doc web pages > > The API Quick Start has been translated to French, German, Japanese and > Spanish! > > We now have German and French index pages: > http://docs.openstack.org/de/ > http://docs.openstack.org/fr/ (proposed - see > https://review.openstack.org/96444) > > For all the guides that are not mentioned on a specific page, we now > have a "secret" page which is not reachable from the main index pages: > > http://docs.openstack.org/draft-i18n-manuals.html > > It lists all the other guides that are currently built. That way > translation teams can easily verify their manuals. > If you like to move one of them to "official" pages, feel free to send a > patch! > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-i18n mailing list > Openstack-i18n at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140530/31d1fce7/attachment.html> From aj at suse.com Fri May 30 04:21:06 2014 From: aj at suse.com (Andreas Jaeger) Date: Fri, 30 May 2014 06:21:06 +0200 Subject: [Openstack-docs] [Openstack-i18n] New localized doc web pages In-Reply-To: <OFD71DFDDC.1852867E-ON48257CE8.000CFFBC-48257CE8.000D2E66@cn.ibm.com> References: <5387490F.80304@suse.com> <OFD71DFDDC.1852867E-ON48257CE8.000CFFBC-48257CE8.000D2E66@cn.ibm.com> Message-ID: <53880732.20404@suse.com> On 05/30/2014 04:22 AM, Ying Chun Guo wrote: > Thanks, Andreas. > How to add documents to the secret page then? Like this: https://review.openstack.org/96517 We publish it like any other page, it's just not reachable from the main entry points, Andreas > Best regards > Ying Chun Guo (Daisy) > > > Andreas Jaeger <aj at suse.com> wrote on 2014/05/29 22:49:51: > >> Andreas Jaeger <aj at suse.com> >> 2014/05/29 22:49 >> >> To >> >> "openstack-docs at lists.openstack.org" <openstack- >> docs at lists.openstack.org>, "openstack-i18n at lists.openstack.org" >> <openstack-i18n at lists.openstack.org>, >> >> cc >> >> Subject >> >> [Openstack-i18n] New localized doc web pages >> >> The API Quick Start has been translated to French, German, Japanese and >> Spanish! >> >> We now have German and French index pages: >> http://docs.openstack.org/de/ >> http://docs.openstack.org/fr/ (proposed - see >> https://review.openstack.org/96444) >> >> For all the guides that are not mentioned on a specific page, we now >> have a "secret" page which is not reachable from the main index pages: >> >> http://docs.openstack.org/draft-i18n-manuals.html >> >> It lists all the other guides that are currently built. That way >> translation teams can easily verify their manuals. >> If you like to move one of them to "official" pages, feel free to send a >> patch! >> >> Andreas >> -- >> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany >> GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 >> >> _______________________________________________ >> Openstack-i18n mailing list >> Openstack-i18n at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n >> > -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From mkassawara at gmail.com Fri May 30 14:44:34 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Fri, 30 May 2014 08:44:34 -0600 Subject: [Openstack-docs] Patch for automated Debian installations Message-ID: <CABA+jQoRDAqgKRj7xKHUFi-xKODX_gL7a-HNgcG8-sJ3epNaUg@mail.gmail.com> I saw this patch for automated Debian installations: https://review.openstack.org/#/c/96695/ I'm concerned that it doesn't agree with the purpose of the installation guide and would like to discuss it further. -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140530/c1e7b60e/attachment.html> From sgordon at redhat.com Fri May 30 15:47:16 2014 From: sgordon at redhat.com (Steve Gordon) Date: Fri, 30 May 2014 11:47:16 -0400 (EDT) Subject: [Openstack-docs] Patch for automated Debian installations In-Reply-To: <CABA+jQoRDAqgKRj7xKHUFi-xKODX_gL7a-HNgcG8-sJ3epNaUg@mail.gmail.com> References: <CABA+jQoRDAqgKRj7xKHUFi-xKODX_gL7a-HNgcG8-sJ3epNaUg@mail.gmail.com> Message-ID: <1954988965.23132074.1401464836421.JavaMail.zimbra@redhat.com> ----- Original Message ----- > From: "Matt Kassawara" <mkassawara at gmail.com> > To: openstack-docs at lists.openstack.org > Sent: Friday, May 30, 2014 10:44:34 AM > Subject: [Openstack-docs] Patch for automated Debian installations > > I saw this patch for automated Debian installations: > > https://review.openstack.org/#/c/96695/ > > I'm concerned that it doesn't agree with the purpose of the installation > guide and would like to discuss it further. Thanks for highlighting this Matt, I am -2 on this submission based on my understanding of our current direction - which appears to match yours - and have recorded my reasoning in the review as follows: "If we were to include this we would also need to open it up to the other distro's automated deployment tools such as PackStack, Crowbar, JuJu, FUEL, Foreman, etc. We have previously decided against this as the aim of the installation guide on docs.o.o is to aid users in learning about the inner workings of OpenStack as they deploy it - not to provide an "easy button". Individual distributions of course can and do maintain their own documentation of the "easy button" elsewhere. An acceptable middle ground might be to provide a section for linking to, but explicitly not endorsing, these external resources." I would add that I am not necessarily in favour of the middle ground I suggest above but thought I would put it out there. Thanks, Steve

From aj at suse.com Fri May 2 07:03:05 2014 From: aj at suse.com (Andreas Jaeger) Date: Fri, 02 May 2014 09:03:05 +0200 Subject: [Openstack-docs] Consistency for "titles" in lists? Message-ID: <53634329.6090206@suse.com> I've seen various forms used during reviews in lists with many items: 1) Boot from image—If you choose ... 2) And also: scheduler_filter_classes - Specifies the list of filter And then the usage of 3) with , 4) ":" instead of —, 5) &ndash or "-" I've seen recently some patches using the first variant but there's a lot of variations. Do we want to have a consistent style for new changes? And which one? This was triggered by reviewing https://review.openstack.org/91736, https://review.openstack.org/90625 and then editing config-reference/compute/section_compute-cells.xml Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From tom at openstack.org Fri May 2 07:07:56 2014 From: tom at openstack.org (Tom Fifield) Date: Fri, 02 May 2014 15:07:56 +0800 Subject: [Openstack-docs] Add release version to config reference options Message-ID: <5363444C.5010801@openstack.org> Hi, Related to our critical Bug #1191447: Clearly mark outdated doc pages, I have proposed a new blueprint for Juno "Add release version to config reference options" https://blueprints.launchpad.net/openstack-manuals/+spec/add-release-version-to-config-reference-options The continuously published configuration reference contains tables with information about all configuration options in OpenStack. Currently, these tables are updated from master, and always have the latest information in them. However, there continues to be users of older releases who still need reference information for their configuration options. The toolchain used to generate the tables is able to operate on any git repository checkout, meaning it can also generate historical tables. This blueprint proposes to automatically provide some form of release information with the configuration option by comparing the options generated from two different repositories. For example * an option that appears in a Havana repository, but does not appear in an Icehouse repository was deprecated in Havana. * an option that does not exist in Grizzly, but appears in Havana is a new option to Havana These sort of cases should then be communicated to the reader. A selection between three potential forms for this information are envisaged: 1. tables are updated with an additional column that provides release information (eg "available from Icehouse onwards", "deprecated in Essex") 2. a table of "new and removed" options between Icehouse and Juno is added as an appendix 3. the configuration reference is branched for the Juno release, with different versions of the tables in each Your thoughts are desired. It's also highly unlikely I will have time to work on this myself, so if someone likes the idea so much they want to step up and do it please volunteer! Regards, Tom From aj at suse.com Fri May 2 07:21:51 2014 From: aj at suse.com (Andreas Jaeger) Date: Fri, 02 May 2014 09:21:51 +0200 Subject: [Openstack-docs] Add release version to config reference options In-Reply-To: <5363444C.5010801@openstack.org> References: <5363444C.5010801@openstack.org> Message-ID: <5363478F.5000402@suse.com> On 05/02/2014 09:07 AM, Tom Fifield wrote: > Hi, > > Related to our critical Bug #1191447: Clearly mark outdated doc pages, > I have proposed a new blueprint for Juno > > "Add release version to config reference options" > > https://blueprints.launchpad.net/openstack-manuals/+spec/add-release-version-to-config-reference-options > > > The continuously published configuration reference contains tables with > information about all configuration options in OpenStack. > > Currently, these tables are updated from master, and always have the > latest information in them. > > However, there continues to be users of older releases who still need > reference information for their configuration options. > > The toolchain used to generate the tables is able to operate on any git > repository checkout, meaning it can also generate historical tables. > > This blueprint proposes to automatically provide some form of release > information with the configuration option by comparing the options > generated from two different repositories. > > For example > * an option that appears in a Havana repository, but does not appear in > an Icehouse repository was deprecated in Havana. > * an option that does not exist in Grizzly, but appears in Havana is a > new option to Havana > > These sort of cases should then be communicated to the reader. A > selection between three potential forms for this information are envisaged: > 1. tables are updated with an additional column that provides release > information (eg "available from Icehouse onwards", "deprecated in Essex") > 2. a table of "new and removed" options between Icehouse and Juno is > added as an appendix > 3. the configuration reference is branched for the Juno release, with > different versions of the tables in each We do branch the configuration reference already, so the current version should be Icehouse only - since we haven't branched - and there's a Havana version out as well. I like your idea with "new in Icehouse" etc., still I fear the basic problem is that users look at the wrong guide. What triggered your suggestion? Do we need to say more prominently "Configuration reference for ICEHOUSE" ? Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From tom at openstack.org Fri May 2 06:51:31 2014 From: tom at openstack.org (Tom Fifield) Date: Fri, 02 May 2014 14:51:31 +0800 Subject: [Openstack-docs] Keep up the great work on the bugs :) Message-ID: <53634073.9070805@openstack.org> See attached - I just noticed that if we fix about 20 more bugs, we'll reach levels we haven't been at since July 2013. It would be amazing to see our backlog reduced to nothing so we can focus on Juno ;) Regards, Tom -------------- next part -------------- A non-text attachment was scrubbed... Name: manuals-bugs-may-2014.png Type: image/png Size: 71203 bytes Desc: not available URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140502/982b1e04/attachment-0001.png> From anne at openstack.org Fri May 2 17:53:42 2014 From: anne at openstack.org (Anne Gentle) Date: Fri, 2 May 2014 12:53:42 -0500 Subject: [Openstack-docs] Consistency for "titles" in lists? In-Reply-To: <53634329.6090206@suse.com> References: <53634329.6090206@suse.com> Message-ID: <CAD0KtVH8uxEQ4r1-qGWsiw1-JvH_NQxo3ST+h1eJg1P5SYLiVA@mail.gmail.com> I looked up Rackspace style and for a list that provides terms and more information that is not meant to be marked up as a variable list, it's: term space emdash space definition phrase period Example: - *Public* ? This setting allows any two servers with public IP addresses to be load balanced. These can be nodes outside of the Rackspace network, but if they are, standard bandwidth rates apply. I'd like to have someone at RedHat look up their style guide and let us know. Ideally we'll be able to answer these if Rackspace or RedHat gets their style guide externalized so we can look it up. Thanks, Anne On Fri, May 2, 2014 at 2:03 AM, Andreas Jaeger <aj at suse.com> wrote: > I've seen various forms used during reviews in lists with many items: > > 1) > <listitem><para><guilabel>Boot from image</guilabel>—If you choose > ... > > 2) And also: > <listitem> > <para><code>scheduler_filter_classes</code> - Specifies the list of filter > > And then the usage of > 3) <formalpara> with <title>, > > 4) ":" instead of —, > 5) &ndash or "-" > > I've seen recently some patches using the first variant but there's a lot > of variations. Do we want to have a consistent style for new changes? And > which one? > > This was triggered by reviewing https://review.openstack.org/91736, > https://review.openstack.org/90625 and then editing > config-reference/compute/section_compute-cells.xml > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140502/b442e93c/attachment.html> From anne at openstack.org Fri May 2 17:54:44 2014 From: anne at openstack.org (Anne Gentle) Date: Fri, 2 May 2014 12:54:44 -0500 Subject: [Openstack-docs] Add release version to config reference options In-Reply-To: <5363478F.5000402@suse.com> References: <5363444C.5010801@openstack.org> <5363478F.5000402@suse.com> Message-ID: <CAD0KtVGBjXGSGdU3xt-OSC+NZ4Y-jwsS_t6KRXDc1FKFW8=3QA@mail.gmail.com> On Fri, May 2, 2014 at 2:21 AM, Andreas Jaeger <aj at suse.com> wrote: > On 05/02/2014 09:07 AM, Tom Fifield wrote: > >> Hi, >> >> Related to our critical Bug #1191447: Clearly mark outdated doc pages, >> I have proposed a new blueprint for Juno >> >> "Add release version to config reference options" >> >> https://blueprints.launchpad.net/openstack-manuals/+spec/ >> add-release-version-to-config-reference-options >> >> >> The continuously published configuration reference contains tables with >> information about all configuration options in OpenStack. >> >> Currently, these tables are updated from master, and always have the >> latest information in them. >> >> However, there continues to be users of older releases who still need >> reference information for their configuration options. >> >> The toolchain used to generate the tables is able to operate on any git >> repository checkout, meaning it can also generate historical tables. >> >> This blueprint proposes to automatically provide some form of release >> information with the configuration option by comparing the options >> generated from two different repositories. >> >> For example >> * an option that appears in a Havana repository, but does not appear in >> an Icehouse repository was deprecated in Havana. >> * an option that does not exist in Grizzly, but appears in Havana is a >> new option to Havana >> >> These sort of cases should then be communicated to the reader. A >> selection between three potential forms for this information are >> envisaged: >> 1. tables are updated with an additional column that provides release >> information (eg "available from Icehouse onwards", "deprecated in Essex") >> 2. a table of "new and removed" options between Icehouse and Juno is >> added as an appendix >> 3. the configuration reference is branched for the Juno release, with >> different versions of the tables in each >> > > We do branch the configuration reference already, so the current version > should be Icehouse only - since we haven't branched - and there's a Havana > version out as well. > > I like your idea with "new in Icehouse" etc., still I fear the basic > problem is that users look at the wrong guide. What triggered your > suggestion? > > Do we need to say more prominently "Configuration reference for ICEHOUSE" ? > > Yep, as Andreas said, we do this already but just haven't yet for Icehouse. Let us know the root cause of the request. Thanks, Anne > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140502/c0e26f8e/attachment.html> From aj at suse.com Fri May 2 19:16:22 2014 From: aj at suse.com (Andreas Jaeger) Date: Fri, 02 May 2014 21:16:22 +0200 Subject: [Openstack-docs] Consistency for "titles" in lists? In-Reply-To: <CAD0KtVH8uxEQ4r1-qGWsiw1-JvH_NQxo3ST+h1eJg1P5SYLiVA@mail.gmail.com> References: <53634329.6090206@suse.com> <CAD0KtVH8uxEQ4r1-qGWsiw1-JvH_NQxo3ST+h1eJg1P5SYLiVA@mail.gmail.com> Message-ID: <5363EF06.3070705@suse.com> On 05/02/2014 07:53 PM, Anne Gentle wrote: > I looked up Rackspace style and for a list that provides terms and more > information that is not meant to be marked up as a variable list, it's: > > term space emdash space definition phrase period > > Example: > > * *Public* ? This setting allows any two servers with public IP > addresses to be load balanced. These can be nodes outside of the > Rackspace network, but if they are, standard bandwidth rates apply. > > > I'd like to have someone at RedHat look up their style guide and let us > know. For the Operations Guide, we used - as specified by O'Reilly's guide - no spaces around the emdashes. What does the Rackspace guide say about the markup for term? Is it emphasis in "bold"? > Ideally we'll be able to answer these if Rackspace or RedHat gets their > style guide externalized so we can look it up. Andreas > Thanks, > Anne > > > On Fri, May 2, 2014 at 2:03 AM, Andreas Jaeger <aj at suse.com > <mailto:aj at suse.com>> wrote: > > I've seen various forms used during reviews in lists with many items: > > 1) > <listitem><para><guilabel>Boot from image</guilabel>—If you choose > ... > > 2) And also: > <listitem> > <para><code>scheduler_filter___classes</code> - Specifies the list > of filter > > And then the usage of > 3) <formalpara> with <title>, > > 4) ":" instead of —, > 5) &ndash or "-" > > I've seen recently some patches using the first variant but there's > a lot of variations. Do we want to have a consistent style for new > changes? And which one? > > This was triggered by reviewing https://review.openstack.org/__91736 > <https://review.openstack.org/91736>, > https://review.openstack.org/__90625 > <https://review.openstack.org/90625> and then editing > config-reference/compute/__section_compute-cells.xml > > Andreas > -- > Andreas Jaeger aj@{suse.com <http://suse.com>,opensuse.org > <http://opensuse.org>} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG > N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 > A126 > > _________________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org> > http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs > <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> > > -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Fri May 2 19:24:55 2014 From: anne at openstack.org (Anne Gentle) Date: Fri, 2 May 2014 14:24:55 -0500 Subject: [Openstack-docs] Consistency for "titles" in lists? In-Reply-To: <5363EF06.3070705@suse.com> References: <53634329.6090206@suse.com> <CAD0KtVH8uxEQ4r1-qGWsiw1-JvH_NQxo3ST+h1eJg1P5SYLiVA@mail.gmail.com> <5363EF06.3070705@suse.com> Message-ID: <CAD0KtVHR-LoJPYxATWL3zNaeDONe4D-LAPRsG4+Yvt_8w=ODwA@mail.gmail.com> On Fri, May 2, 2014 at 2:16 PM, Andreas Jaeger <aj at suse.com> wrote: > On 05/02/2014 07:53 PM, Anne Gentle wrote: > >> I looked up Rackspace style and for a list that provides terms and more >> information that is not meant to be marked up as a variable list, it's: >> >> term space emdash space definition phrase period >> >> Example: >> >> * *Public* ? This setting allows any two servers with public IP >> >> addresses to be load balanced. These can be nodes outside of the >> Rackspace network, but if they are, standard bandwidth rates apply. >> >> >> I'd like to have someone at RedHat look up their style guide and let us >> know. >> > > For the Operations Guide, we used - as specified by O'Reilly's guide - no > spaces around the emdashes. > > Technical these examples ARE variable lists and O'Reilly's style wants it written as such. http://chimera.labs.oreilly.com/books/1230000000969/ch02.html#variable_list Frequently, bulleted lists should be converted to variable lists. Any bulleted list whose entries consist of a short term and its definition should be converted. For example, the following bulleted list entries: - Spellchecking: process of correcting spelling - Pagebreaking?process of breaking pages should be variable list entries: SpellcheckingProcess of correcting spelling PagebreakingProcess of breaking pages > > What does the Rackspace guide say about the markup for term? Is it > emphasis in "bold"? No additional markup for the term. > > > Ideally we'll be able to answer these if Rackspace or RedHat gets their >> style guide externalized so we can look it up. >> > > > Andreas > > Thanks, >> Anne >> >> >> On Fri, May 2, 2014 at 2:03 AM, Andreas Jaeger <aj at suse.com >> <mailto:aj at suse.com>> wrote: >> >> I've seen various forms used during reviews in lists with many items: >> >> 1) >> <listitem><para><guilabel>Boot from image</guilabel>—If you >> choose >> ... >> >> 2) And also: >> <listitem> >> <para><code>scheduler_filter___classes</code> - Specifies the list >> >> of filter >> >> And then the usage of >> 3) <formalpara> with <title>, >> >> 4) ":" instead of —, >> 5) &ndash or "-" >> >> I've seen recently some patches using the first variant but there's >> a lot of variations. Do we want to have a consistent style for new >> changes? And which one? >> >> This was triggered by reviewing https://review.openstack.org/__91736 >> <https://review.openstack.org/91736>, >> https://review.openstack.org/__90625 >> >> <https://review.openstack.org/90625> and then editing >> config-reference/compute/__section_compute-cells.xml >> >> Andreas >> -- >> Andreas Jaeger aj@{suse.com <http://suse.com>,opensuse.org >> <http://opensuse.org>} Twitter/Identica: jaegerandi >> >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany >> GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG >> N?rnberg) >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 >> A126 >> >> _________________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org> >> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__ >> openstack-docs >> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> >> >> >> > > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140502/0747ccf7/attachment-0001.html> From aj at suse.com Fri May 2 20:12:07 2014 From: aj at suse.com (Andreas Jaeger) Date: Fri, 02 May 2014 22:12:07 +0200 Subject: [Openstack-docs] Consistency for "titles" in lists? In-Reply-To: <CAD0KtVHR-LoJPYxATWL3zNaeDONe4D-LAPRsG4+Yvt_8w=ODwA@mail.gmail.com> References: <53634329.6090206@suse.com> <CAD0KtVH8uxEQ4r1-qGWsiw1-JvH_NQxo3ST+h1eJg1P5SYLiVA@mail.gmail.com> <5363EF06.3070705@suse.com> <CAD0KtVHR-LoJPYxATWL3zNaeDONe4D-LAPRsG4+Yvt_8w=ODwA@mail.gmail.com> Message-ID: <5363FC17.3080400@suse.com> On 05/02/2014 09:24 PM, Anne Gentle wrote: > > > > On Fri, May 2, 2014 at 2:16 PM, Andreas Jaeger <aj at suse.com > <mailto:aj at suse.com>> wrote: > > On 05/02/2014 07:53 PM, Anne Gentle wrote: > > I looked up Rackspace style and for a list that provides terms > and more > information that is not meant to be marked up as a variable > list, it's: > > term space emdash space definition phrase period > > Example: > > * *Public* ? This setting allows any two servers with public IP > > addresses to be load balanced. These can be nodes outside > of the > Rackspace network, but if they are, standard bandwidth > rates apply. > > > I'd like to have someone at RedHat look up their style guide and > let us > know. > > > For the Operations Guide, we used - as specified by O'Reilly's guide > - no spaces around the emdashes. > > > Technical these examples ARE variable lists and O'Reilly's style wants > it written as such. > http://chimera.labs.oreilly.com/books/1230000000969/ch02.html#variable_list I agree that they are indeed variable lists - but we haven't followed the markup usage in the manuals. I'm fine with whatever convention we agree on, my goal is to have consistency for new text and changes. > Frequently, bulleted lists should be converted to variable lists. Any > bulleted list whose entries consist of a short term and its definition > should be converted. For example, the following bulleted list entries: > > * Spellchecking: process of correcting spelling > * Pagebreaking?process of breaking pages > > should be variable list entries: > > Spellchecking > Process of correcting spelling > Pagebreaking > Process of breaking pages So, these two reviews: https://review.openstack.org/91736 https://review.openstack.org/90625 should get a -1 because of not using variable lists? Do we agree on this convention? Then I'll make it a bit clearer in the conventions wiki page and will review accordingly. > > What does the Rackspace guide say about the markup for term? Is it > emphasis in "bold"? > > > No additional markup for the term. That's different from what is used in many places in the manuals and if we go to variable lists, it is mood. thanks, Andreas > > > Ideally we'll be able to answer these if Rackspace or RedHat > gets their > style guide externalized so we can look it up. > > > > Andreas > > Thanks, > Anne > > > On Fri, May 2, 2014 at 2:03 AM, Andreas Jaeger <aj at suse.com > <mailto:aj at suse.com> > <mailto:aj at suse.com <mailto:aj at suse.com>>> wrote: > > I've seen various forms used during reviews in lists with > many items: > > 1) > <listitem><para><guilabel>Boot from > image</guilabel>—If you choose > ... > > 2) And also: > <listitem> > <para><code>scheduler_filter_____classes</code> - Specifies > the list > > of filter > > And then the usage of > 3) <formalpara> with <title>, > > 4) ":" instead of —, > 5) &ndash or "-" > > I've seen recently some patches using the first variant but > there's > a lot of variations. Do we want to have a consistent style > for new > changes? And which one? > > This was triggered by reviewing > https://review.openstack.org/____91736 > <https://review.openstack.org/__91736> > <https://review.openstack.org/__91736 > <https://review.openstack.org/91736>>, > https://review.openstack.org/____90625 > <https://review.openstack.org/__90625> > > <https://review.openstack.org/__90625 > <https://review.openstack.org/90625>> and then editing > config-reference/compute/____section_compute-cells.xml > > Andreas > -- > Andreas Jaeger aj@{suse.com <http://suse.com> > <http://suse.com>,opensuse.org <http://opensuse.org> > <http://opensuse.org>} Twitter/Identica: jaegerandi > > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, > Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG > N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A > 563C C272 > A126 > > ___________________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.__opensta__ck.org <http://openstack.org> > <mailto:Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org>> > http://lists.openstack.org/____cgi-bin/mailman/listinfo/____openstack-docs > <http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs> > > <http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs > <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs>> > > > > > -- > Andreas Jaeger aj@{suse.com <http://suse.com>,opensuse.org > <http://opensuse.org>} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG > N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 > A126 > > _________________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org> > http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs > <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> > > -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From diane.fleming at RACKSPACE.COM Fri May 2 20:19:28 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Fri, 2 May 2014 20:19:28 +0000 Subject: [Openstack-docs] Consistency for "titles" in lists? In-Reply-To: <5363FC17.3080400@suse.com> Message-ID: <CF8967B9.2C115%diane.fleming@rackspace.com> Generally, we (or at least I do) "bold" the terms in variable lists because they look a little weird without the bolding. However, someone could open a bug to make <term>xx</term> items bold by default. Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com On 5/2/14 3:12 PM, "Andreas Jaeger" <aj at suse.com> wrote: >On 05/02/2014 09:24 PM, Anne Gentle wrote: >> >> >> >> On Fri, May 2, 2014 at 2:16 PM, Andreas Jaeger <aj at suse.com >> <mailto:aj at suse.com>> wrote: >> >> On 05/02/2014 07:53 PM, Anne Gentle wrote: >> >> I looked up Rackspace style and for a list that provides terms >> and more >> information that is not meant to be marked up as a variable >> list, it's: >> >> term space emdash space definition phrase period >> >> Example: >> >> * *Public* ? This setting allows any two servers with public >>IP >> >> addresses to be load balanced. These can be nodes outside >> of the >> Rackspace network, but if they are, standard bandwidth >> rates apply. >> >> >> I'd like to have someone at RedHat look up their style guide and >> let us >> know. >> >> >> For the Operations Guide, we used - as specified by O'Reilly's guide >> - no spaces around the emdashes. >> >> >> Technical these examples ARE variable lists and O'Reilly's style wants >> it written as such. >> >>http://chimera.labs.oreilly.com/books/1230000000969/ch02.html#variable_li >>st > >I agree that they are indeed variable lists - but we haven't followed >the markup usage in the manuals. > >I'm fine with whatever convention we agree on, my goal is to have >consistency for new text and changes. > >> Frequently, bulleted lists should be converted to variable lists. Any >> bulleted list whose entries consist of a short term and its definition >> should be converted. For example, the following bulleted list entries: >> >> * Spellchecking: process of correcting spelling >> * Pagebreaking?process of breaking pages >> >> should be variable list entries: >> >> Spellchecking >> Process of correcting spelling >> Pagebreaking >> Process of breaking pages > >So, these two reviews: >https://review.openstack.org/91736 >https://review.openstack.org/90625 > >should get a -1 because of not using variable lists? > >Do we agree on this convention? Then I'll make it a bit clearer in the >conventions wiki page and will review accordingly. > >> >> What does the Rackspace guide say about the markup for term? Is it >> emphasis in "bold"? >> >> >> No additional markup for the term. > >That's different from what is used in many places in the manuals and if >we go to variable lists, it is mood. > >thanks, >Andreas > >> >> >> Ideally we'll be able to answer these if Rackspace or RedHat >> gets their >> style guide externalized so we can look it up. >> >> >> >> Andreas >> >> Thanks, >> Anne >> >> >> On Fri, May 2, 2014 at 2:03 AM, Andreas Jaeger <aj at suse.com >> <mailto:aj at suse.com> >> <mailto:aj at suse.com <mailto:aj at suse.com>>> wrote: >> >> I've seen various forms used during reviews in lists with >> many items: >> >> 1) >> <listitem><para><guilabel>Boot from >> image</guilabel>—If you choose >> ... >> >> 2) And also: >> <listitem> >> <para><code>scheduler_filter_____classes</code> - Specifies >> the list >> >> of filter >> >> And then the usage of >> 3) <formalpara> with <title>, >> >> 4) ":" instead of —, >> 5) &ndash or "-" >> >> I've seen recently some patches using the first variant but >> there's >> a lot of variations. Do we want to have a consistent style >> for new >> changes? And which one? >> >> This was triggered by reviewing >> https://review.openstack.org/____91736 >> <https://review.openstack.org/__91736> >> <https://review.openstack.org/__91736 >> <https://review.openstack.org/91736>>, >> https://review.openstack.org/____90625 >> <https://review.openstack.org/__90625> >> >> <https://review.openstack.org/__90625 >> <https://review.openstack.org/90625>> and then editing >> config-reference/compute/____section_compute-cells.xml >> >> Andreas >> -- >> Andreas Jaeger aj@{suse.com <http://suse.com> >> <http://suse.com>,opensuse.org <http://opensuse.org> >> <http://opensuse.org>} Twitter/Identica: jaegerandi >> >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, >> Germany >> GF: Jeff Hawn,Jennifer Guild,Felix >>Imend?rffer,HRB16746 (AG >> N?rnberg) >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A >> 563C C272 >> A126 >> >> ___________________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.__opensta__ck.org >><http://openstack.org> >> <mailto:Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org>> >> >>http://lists.openstack.org/____cgi-bin/mailman/listinfo/____openstack-doc >>s >> >><http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs> >> >> >><http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs >> >><http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs>> >> >> >> >> >> -- >> Andreas Jaeger aj@{suse.com <http://suse.com>,opensuse.org >> <http://opensuse.org>} Twitter/Identica: jaegerandi >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany >> GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG >> N?rnberg) >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 >> A126 >> >> _________________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org> >> >>http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs >> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> >> >> > > >-- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > >_______________________________________________ >Openstack-docs mailing list >Openstack-docs at lists.openstack.org >http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs From shaunm at gnome.org Sat May 3 12:53:02 2014 From: shaunm at gnome.org (Shaun McCance) Date: Sat, 03 May 2014 07:53:02 -0500 Subject: [Openstack-docs] Switch to itstool for docs translation? Message-ID: <1399121582.24585.10.camel@verso> Hi all, I've been working on switching the docs translation infrastructure over to itstool. This affects openstack-manuals, operations-guide, and api-site. The current tools are based on xml2po, but they don't call xml2po directly. Instead, they import xml2po and mess around with its internals to get some custom behavior. itstool is designed to handle custom behavior with rules from the W3C Internationalization Tag Set (ITS). You can see the ITS I put together so far here: https://review.openstack.org/#/c/91869/3/os_doc_tools/resources/openstack.its,unified Using ITS also allows us to do local ITS attributes to override the behavior for specific elements. See a simple example here: https://review.openstack.org/#/c/91872/1/api-quick-start/src/docbkx/api-quick-start-intro.xml,unified Most messages in the PO files will be the same. The one big difference will be in how placeholders are done when there's a block-level element inside a block-level element (a practice I discourage anyway). Blueprint and some patches: https://blueprints.launchpad.net/openstack-manuals/+spec/itstool-for-docs https://review.openstack.org/#/q/topic:bp/itstool-for-docs,n,z I'd like to get input from translators, as well as any other docs folks who've worked on this. Most of the document translations are incomplete anyway, but it would nevertheless be best to do this at the beginning of a release cycle. -- Shaun From aj at suse.com Sat May 3 16:03:07 2014 From: aj at suse.com (Andreas Jaeger) Date: Sat, 03 May 2014 18:03:07 +0200 Subject: [Openstack-docs] time to Branch for icehouse? Message-ID: <5365133B.3010400@suse.com> Having looked at the open bugs and the reviews of the last days, it seems we've done a great job with Install Guide and Config Reference and we can safely branch now. What do you think? Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From sgordon at redhat.com Sat May 3 17:36:21 2014 From: sgordon at redhat.com (Steve Gordon) Date: Sat, 3 May 2014 13:36:21 -0400 (EDT) Subject: [Openstack-docs] time to Branch for icehouse? In-Reply-To: <5365133B.3010400@suse.com> References: <5365133B.3010400@suse.com> Message-ID: <774235864.66768.1399138581471.JavaMail.zimbra@redhat.com> ----- Original Message ----- > Having looked at the open bugs and the reviews of the last days, it > seems we've done a great job with Install Guide and Config Reference and > we can safely branch now. > > What do you think? > > Andreas +1 from me. -Steve From anne at openstack.org Sat May 3 20:49:19 2014 From: anne at openstack.org (Anne Gentle) Date: Sat, 3 May 2014 15:49:19 -0500 Subject: [Openstack-docs] time to Branch for icehouse? In-Reply-To: <5365133B.3010400@suse.com> References: <5365133B.3010400@suse.com> Message-ID: <CAD0KtVERMv0_67M2Z+kaxyK5OpO-okkFs=ZgGe8whSzbJRCt=Q@mail.gmail.com> On Sat, May 3, 2014 at 11:03 AM, Andreas Jaeger <aj at suse.com> wrote: > Having looked at the open bugs and the reviews of the last days, it seems > we've done a great job with Install Guide and Config Reference and we can > safely branch now. > > What do you think? I'm up for it. Or I'm down with that. Whichever. :) > > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140503/3f356211/attachment.html> From mkassawara at gmail.com Sat May 3 23:01:07 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Sat, 3 May 2014 17:01:07 -0600 Subject: [Openstack-docs] time to Branch for icehouse? In-Reply-To: <CAD0KtVERMv0_67M2Z+kaxyK5OpO-okkFs=ZgGe8whSzbJRCt=Q@mail.gmail.com> References: <5365133B.3010400@suse.com> <CAD0KtVERMv0_67M2Z+kaxyK5OpO-okkFs=ZgGe8whSzbJRCt=Q@mail.gmail.com> Message-ID: <CABA+jQpFOBKsXz8p6iXiDAmDq4Vx+A1jN22DR3a=hZtZHZoGOw@mail.gmail.com> Go for it! On Sat, May 3, 2014 at 2:49 PM, Anne Gentle <anne at openstack.org> wrote: > > > > On Sat, May 3, 2014 at 11:03 AM, Andreas Jaeger <aj at suse.com> wrote: > >> Having looked at the open bugs and the reviews of the last days, it seems >> we've done a great job with Install Guide and Config Reference and we can >> safely branch now. >> >> What do you think? > > > > I'm up for it. Or I'm down with that. Whichever. :) > > >> >> >> Andreas >> -- >> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany >> GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140503/8396651f/attachment.html> From aj at suse.com Sun May 4 00:13:02 2014 From: aj at suse.com (Andreas Jaeger) Date: Sun, 04 May 2014 02:13:02 +0200 Subject: [Openstack-docs] time to Branch for icehouse? In-Reply-To: <CAD0KtVERMv0_67M2Z+kaxyK5OpO-okkFs=ZgGe8whSzbJRCt=Q@mail.gmail.com> References: <5365133B.3010400@suse.com> <CAD0KtVERMv0_67M2Z+kaxyK5OpO-okkFs=ZgGe8whSzbJRCt=Q@mail.gmail.com> Message-ID: <5365860E.7020506@suse.com> On 05/03/2014 10:49 PM, Anne Gentle wrote: > > > > On Sat, May 3, 2014 at 11:03 AM, Andreas Jaeger <aj at suse.com > <mailto:aj at suse.com>> wrote: > > Having looked at the open bugs and the reviews of the last days, it > seems we've done a great job with Install Guide and Config Reference > and we can safely branch now. > > What do you think? > > > > I'm up for it. Or I'm down with that. Whichever. :) Before we branch, please include this patch so that publishing is not done to both trunk and icehouse anymore: https://review.openstack.org/91971 Once we have branched, we should change the publishdocs section on the stable/icehouse branch to just: commands = openstack-doc-test --check-build --publish --only-book install-guide --only-book config-reference This is the same what we do on stable/havana, Andreas > > > Andreas > -- > Andreas Jaeger aj@{suse.com <http://suse.com>,opensuse.org > <http://opensuse.org>} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG > N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 > A126 > > _________________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org> > http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs > <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> > > > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Sun May 4 11:33:29 2014 From: aj at suse.com (Andreas Jaeger) Date: Sun, 04 May 2014 13:33:29 +0200 Subject: [Openstack-docs] [Openstack-i18n] Switch to itstool for docs translation? In-Reply-To: <1399121582.24585.10.camel@verso> References: <1399121582.24585.10.camel@verso> Message-ID: <53662589.2090504@suse.com> On 05/03/2014 02:53 PM, Shaun McCance wrote: > Hi all, > > I've been working on switching the docs translation infrastructure over > to itstool. This affects openstack-manuals, operations-guide, and > api-site. The current tools are based on xml2po, but they don't call > xml2po directly. Instead, they import xml2po and mess around with its > internals to get some custom behavior. > > itstool is designed to handle custom behavior with rules from the W3C > Internationalization Tag Set (ITS). You can see the ITS I put together > so far here: > > https://review.openstack.org/#/c/91869/3/os_doc_tools/resources/openstack.its,unified > > Using ITS also allows us to do local ITS attributes to override the > behavior for specific elements. See a simple example here: > > https://review.openstack.org/#/c/91872/1/api-quick-start/src/docbkx/api-quick-start-intro.xml,unified > > Most messages in the PO files will be the same. The one big difference > will be in how placeholders are done when there's a block-level element > inside a block-level element (a practice I discourage anyway). Could you give an example, please? > Blueprint and some patches: > > https://blueprints.launchpad.net/openstack-manuals/+spec/itstool-for-docs > https://review.openstack.org/#/q/topic:bp/itstool-for-docs,n,z Looking at the patches, I really like what I see and would love to see us move forward. This needs also some documentation in the OpenStack wiki on the recommend usage of local ITS attributes like its:translate and its:withinText. > I'd like to get input from translators, as well as any other docs folks > who've worked on this. Most of the document translations are incomplete > anyway, but it would nevertheless be best to do this at the beginning of > a release cycle. I assume that we can convert the existing translated files in such a way that we do not loose translations? How to do this properly? Download current files from transifex, convert into new format, upload converted files - and then continue translating? Or will it be enough to upload the pot file and let transfix do the translation? Did you test a conversation of locale files and reconstructed translated manuals? Is this just working with the updated tools or are additional steps needed? I think we need to ensure with the infra team that itstools are installed on our machines. I see that some patches are dependent on each other and we need to do certain steps in a specific order. Is this something you can write down as plan, please? Thanks! Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From slong at redhat.com Mon May 5 00:59:49 2014 From: slong at redhat.com (Summer Long) Date: Sun, 4 May 2014 20:59:49 -0400 (EDT) Subject: [Openstack-docs] time to Branch for icehouse? In-Reply-To: <5365860E.7020506@suse.com> References: <5365133B.3010400@suse.com> <CAD0KtVERMv0_67M2Z+kaxyK5OpO-okkFs=ZgGe8whSzbJRCt=Q@mail.gmail.com> <5365860E.7020506@suse.com> Message-ID: <1879856974.225639.1399251589083.JavaMail.zimbra@redhat.com> Have a couple of patches on review I'd like to include first? Got caught out by the 'term=value' spacing issue. -- Summer Long OpenStack Documentation Lead Engineering Content Services Red Hat Asia Pacific Brisbane, Australia slong at redhat.com | irc: slong ----- Original Message ----- > From: "Andreas Jaeger" <aj at suse.com> > To: "Anne Gentle" <anne at openstack.org> > Cc: openstack-docs at lists.openstack.org > Sent: Sunday, May 4, 2014 10:13:02 AM > Subject: Re: [Openstack-docs] time to Branch for icehouse? > > On 05/03/2014 10:49 PM, Anne Gentle wrote: > > > > > > > > On Sat, May 3, 2014 at 11:03 AM, Andreas Jaeger <aj at suse.com > > <mailto:aj at suse.com>> wrote: > > > > Having looked at the open bugs and the reviews of the last days, it > > seems we've done a great job with Install Guide and Config Reference > > and we can safely branch now. > > > > What do you think? > > > > > > > > I'm up for it. Or I'm down with that. Whichever. :) > > Before we branch, please include this patch so that publishing > is not done to both trunk and icehouse anymore: > https://review.openstack.org/91971 > > Once we have branched, we should change the publishdocs > section on the stable/icehouse branch to just: > commands = > openstack-doc-test --check-build --publish --only-book install-guide > --only-book config-reference > > This is the same what we do on stable/havana, > > Andreas > > > > > > > Andreas > > -- > > Andreas Jaeger aj@{suse.com <http://suse.com>,opensuse.org > > <http://opensuse.org>} Twitter/Identica: jaegerandi > > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG > > N?rnberg) > > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 > > A126 > > > > _________________________________________________ > > Openstack-docs mailing list > > Openstack-docs at lists.__openstack.org > > <mailto:Openstack-docs at lists.openstack.org> > > http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs > > <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> > > > > > > > > > > _______________________________________________ > > Openstack-docs mailing list > > Openstack-docs at lists.openstack.org > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > > > > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > From aj at suse.com Mon May 5 04:35:19 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 05 May 2014 06:35:19 +0200 Subject: [Openstack-docs] time to Branch for icehouse? In-Reply-To: <1879856974.225639.1399251589083.JavaMail.zimbra@redhat.com> References: <5365133B.3010400@suse.com> <CAD0KtVERMv0_67M2Z+kaxyK5OpO-okkFs=ZgGe8whSzbJRCt=Q@mail.gmail.com> <5365860E.7020506@suse.com> <1879856974.225639.1399251589083.JavaMail.zimbra@redhat.com> Message-ID: <53671507.1040906@suse.com> On 05/05/2014 02:59 AM, Summer Long wrote: > Have a couple of patches on review I'd like to include first? Got caught out by the 'term=value' spacing issue. > We can backport as usual ;) But yeah, let's see what we can get reviewed quickly, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From berendt at b1-systems.de Mon May 5 09:27:39 2014 From: berendt at b1-systems.de (Christian Berendt) Date: Mon, 05 May 2014 11:27:39 +0200 Subject: [Openstack-docs] [cli-reference] change "command client client" to "command line interface"? Message-ID: <5367598B.5010306@b1-systems.de> The name of the cli-reference is "OpenStack Command-Line Interface Reference". Inside the document we're always using "xyz command-line client(s)". Should we rename the document to "OpenStack Command-Line Client Reference" or should we rename all occurrences of "command-line client" to "command-line interface"? Christian. -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 From berendt at b1-systems.de Mon May 5 10:09:45 2014 From: berendt at b1-systems.de (Christian Berendt) Date: Mon, 05 May 2014 12:09:45 +0200 Subject: [Openstack-docs] How to fix typos in pot files? Message-ID: <53676369.1090303@b1-systems.de> I found a little typo in two pot files. common/locale/common.pot install-guide/locale/install-guide.pot How can I fix those files? Can I modify them in-tree? Christian. -- Christian Berendt Cloud Computing Solution Architect Tel.: +49-171-5542175 Mail: berendt at b1-systems.de B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 From aj at suse.com Mon May 5 11:06:46 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 05 May 2014 13:06:46 +0200 Subject: [Openstack-docs] How to fix typos in pot files? In-Reply-To: <53676369.1090303@b1-systems.de> References: <53676369.1090303@b1-systems.de> Message-ID: <536770C6.1010907@suse.com> On 05/05/2014 12:09 PM, Christian Berendt wrote: > I found a little typo in two pot files. > > common/locale/common.pot > install-guide/locale/install-guide.pot They are regenerated automatically every morning. Just fix the sources which are wrong. > How can I fix those files? Can I modify them in-tree? Please don't, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From diane.fleming at RACKSPACE.COM Mon May 5 13:33:24 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Mon, 5 May 2014 13:33:24 +0000 Subject: [Openstack-docs] [cli-reference] change "command client client" to "command line interface"? In-Reply-To: <5367598B.5010306@b1-systems.de> References: <5367598B.5010306@b1-systems.de> Message-ID: <DA2F3C02-13D4-46FE-8414-A8C8E9CE32FC@RACKSPACE.COM> Yes, there is a bit of disconnect there. The acronym CLI stands for command-line interface, but the actual python packages are referred to as "clients." My preference would be to rename the book "OpenStack Command Reference" and title each chapter in the book, "Xxx commands" (like Block Storage commands). Then, in the overview section, we can say that users can run commands from the command line or include them in scripts by installing clients. I see no reason for including the word "interface" or "client" in the title or chapter titles. Sent from my iPhone > On May 5, 2014, at 2:30 AM, "Christian Berendt" <berendt at b1-systems.de> wrote: > > The name of the cli-reference is "OpenStack Command-Line Interface Reference". Inside the document we're always using "xyz command-line client(s)". > > Should we rename the document to "OpenStack Command-Line Client Reference" or should we rename all occurrences of "command-line client" to "command-line interface"? > > Christian. > > -- > Christian Berendt > Cloud Computing Solution Architect > Mail: berendt at b1-systems.de > > B1 Systems GmbH > Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de > GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs From eperdomo at cisco.com Mon May 5 18:40:20 2014 From: eperdomo at cisco.com (Edgar Magana Perdomo (eperdomo)) Date: Mon, 5 May 2014 18:40:20 +0000 Subject: [Openstack-docs] time to Branch for icehouse? In-Reply-To: <53671507.1040906@suse.com> References: <5365133B.3010400@suse.com> <CAD0KtVERMv0_67M2Z+kaxyK5OpO-okkFs=ZgGe8whSzbJRCt=Q@mail.gmail.com> <5365860E.7020506@suse.com> <1879856974.225639.1399251589083.JavaMail.zimbra@redhat.com> <53671507.1040906@suse.com> Message-ID: <CF8D2919.FA54%eperdomo@cisco.com> Great Job on the Docs Folks! Edgar On 5/4/14, 9:35 PM, "Andreas Jaeger" <aj at suse.com> wrote: >On 05/05/2014 02:59 AM, Summer Long wrote: >> Have a couple of patches on review I'd like to include first? Got >>caught out by the 'term=value' spacing issue. >> > >We can backport as usual ;) > >But yeah, let's see what we can get reviewed quickly, > >Andreas >-- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > >_______________________________________________ >Openstack-docs mailing list >Openstack-docs at lists.openstack.org >http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs From aj at suse.com Mon May 5 18:40:48 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 05 May 2014 20:40:48 +0200 Subject: [Openstack-docs] Consistency for "titles" in lists? In-Reply-To: <CF8967B9.2C115%diane.fleming@rackspace.com> References: <CF8967B9.2C115%diane.fleming@rackspace.com> Message-ID: <5367DB30.7070903@suse.com> On 05/02/2014 10:19 PM, Diane Fleming wrote: > Generally, we (or at least I do) "bold" the terms in variable lists > because they look a little weird without the bolding. > > However, someone could open a bug to make <term>xx</term> items bold by > default. So, what about the following proposal: 1) File a bug against our tools asking David Cramer to mark <term> as bold in variable lists. 2) Add to conventions (with proper markup examples, enhancing current entry about variable list): For lists that consist of a short term and its definition, variable lists should be used. Any current usage as bulleted list should be converted. For example, the following bulleted list entries: Spellchecking: process of correcting spelling Pagebreaking?process of breaking pages should be variable list entries: Spellchecking Process of correcting spelling Pagebreaking Process of breaking pages Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From diane.fleming at RACKSPACE.COM Mon May 5 19:01:14 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Mon, 5 May 2014 19:01:14 +0000 Subject: [Openstack-docs] Consistency for "titles" in lists? In-Reply-To: <5367DB30.7070903@suse.com> Message-ID: <CF8D2E03.2C40A%diane.fleming@rackspace.com> +1 Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com On 5/5/14 11:40 AM, "Andreas Jaeger" <aj at suse.com> wrote: >On 05/02/2014 10:19 PM, Diane Fleming wrote: >> Generally, we (or at least I do) "bold" the terms in variable lists >> because they look a little weird without the bolding. >> >> However, someone could open a bug to make <term>xx</term> items bold by >> default. > >So, what about the following proposal: > >1) File a bug against our tools asking David Cramer to mark <term> as >bold in variable lists. > >2) Add to conventions (with proper markup examples, enhancing current >entry about variable list): > >For lists that consist of a short term and its definition, variable >lists should be used. > >Any current usage as bulleted list should be converted. For example, the >following bulleted list entries: > > Spellchecking: process of correcting spelling > Pagebreaking?process of breaking pages > >should be variable list entries: > >Spellchecking > Process of correcting spelling >Pagebreaking > Process of breaking pages > >Andreas >-- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From slong at redhat.com Mon May 5 20:08:12 2014 From: slong at redhat.com (Summer Long) Date: Mon, 5 May 2014 16:08:12 -0400 (EDT) Subject: [Openstack-docs] Consistency for "titles" in lists? In-Reply-To: <CF8D2E03.2C40A%diane.fleming@rackspace.com> References: <CF8D2E03.2C40A%diane.fleming@rackspace.com> Message-ID: <635429448.1429695.1399320492199.JavaMail.zimbra@redhat.com> +1 cheers, Summer -- Summer Long OpenStack Documentation Lead Engineering Content Services Red Hat Asia Pacific Brisbane, Australia slong at redhat.com | irc: slong ----- Original Message ----- > From: "Diane Fleming" <diane.fleming at RACKSPACE.COM> > To: "Andreas Jaeger" <aj at suse.com>, "Anne Gentle" <anne at openstack.org> > Cc: openstack-docs at lists.openstack.org > Sent: Tuesday, May 6, 2014 5:01:14 AM > Subject: Re: [Openstack-docs] Consistency for "titles" in lists? > > +1 > Diane > ---------------------------------------------- > Diane Fleming > Software Developer II - US > > diane.fleming at rackspace.com > Cell 512.323.6799 > Office 512.874.1260 > Skype drfleming0227 > Google-plus diane.fleming at gmail.com > > > > > > > On 5/5/14 11:40 AM, "Andreas Jaeger" <aj at suse.com> wrote: > > >On 05/02/2014 10:19 PM, Diane Fleming wrote: > >> Generally, we (or at least I do) "bold" the terms in variable lists > >> because they look a little weird without the bolding. > >> > >> However, someone could open a bug to make <term>xx</term> items bold by > >> default. > > > >So, what about the following proposal: > > > >1) File a bug against our tools asking David Cramer to mark <term> as > >bold in variable lists. > > > >2) Add to conventions (with proper markup examples, enhancing current > >entry about variable list): > > > >For lists that consist of a short term and its definition, variable > >lists should be used. > > > >Any current usage as bulleted list should be converted. For example, the > >following bulleted list entries: > > > > Spellchecking: process of correcting spelling > > Pagebreaking?process of breaking pages > > > >should be variable list entries: > > > >Spellchecking > > Process of correcting spelling > >Pagebreaking > > Process of breaking pages > > > >Andreas > >-- > > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > From anne at openstack.org Mon May 5 21:28:48 2014 From: anne at openstack.org (Anne Gentle) Date: Mon, 5 May 2014 16:28:48 -0500 Subject: [Openstack-docs] Consistency for "titles" in lists? In-Reply-To: <5367DB30.7070903@suse.com> References: <CF8967B9.2C115%diane.fleming@rackspace.com> <5367DB30.7070903@suse.com> Message-ID: <CAD0KtVF70t7LpWJ8sRqU39q8RCkkFyyjwgfTE2R=KhsPhMuCQQ@mail.gmail.com> Sounds good to me. I'd log the bug myself but I'm at Write the Docs and the network is a little slow. On Mon, May 5, 2014 at 1:40 PM, Andreas Jaeger <aj at suse.com> wrote: > On 05/02/2014 10:19 PM, Diane Fleming wrote: > >> Generally, we (or at least I do) "bold" the terms in variable lists >> because they look a little weird without the bolding. >> >> However, someone could open a bug to make <term>xx</term> items bold by >> default. >> > > So, what about the following proposal: > > 1) File a bug against our tools asking David Cramer to mark <term> as bold > in variable lists. > > 2) Add to conventions (with proper markup examples, enhancing current > entry about variable list): > > For lists that consist of a short term and its definition, variable lists > should be used. > > Any current usage as bulleted list should be converted. For example, the > following bulleted list entries: > > > Spellchecking: process of correcting spelling > Pagebreaking?process of breaking pages > > should be variable list entries: > > Spellchecking > Process of correcting spelling > Pagebreaking > Process of breaking pages > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140505/6969d597/attachment.html> From aj at suse.com Tue May 6 19:53:03 2014 From: aj at suse.com (Andreas Jaeger) Date: Tue, 06 May 2014 21:53:03 +0200 Subject: [Openstack-docs] Consistency for "titles" in lists? In-Reply-To: <CF8D2E03.2C40A%diane.fleming@rackspace.com> References: <CF8D2E03.2C40A%diane.fleming@rackspace.com> Message-ID: <53693D9F.2050209@suse.com> I've updated the already great convention - that I apparently overlooked - with the examples given: https://wiki.openstack.org/wiki/Documentation/Conventions#Term.2Fdescription_or_key.2Fvalue_pairs And filled this bug: https://bugs.launchpad.net/openstack-manuals/+bug/1316770 Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From slong at redhat.com Wed May 7 11:57:12 2014 From: slong at redhat.com (Summer Long) Date: Wed, 7 May 2014 07:57:12 -0400 (EDT) Subject: [Openstack-docs] time to Branch for icehouse? In-Reply-To: <53671507.1040906@suse.com> References: <5365133B.3010400@suse.com> <CAD0KtVERMv0_67M2Z+kaxyK5OpO-okkFs=ZgGe8whSzbJRCt=Q@mail.gmail.com> <5365860E.7020506@suse.com> <1879856974.225639.1399251589083.JavaMail.zimbra@redhat.com> <53671507.1040906@suse.com> Message-ID: <718121345.3429152.1399463832116.JavaMail.zimbra@redhat.com> Apologies, have stalled out on bugs, but am not sure on timing anyway. Andreas, did you already branch the Config Ref? thanks, Summer -- Summer Long OpenStack Documentation Lead Engineering Content Services Red Hat Asia Pacific Brisbane, Australia slong at redhat.com | irc: slong ----- Original Message ----- > From: "Andreas Jaeger" <aj at suse.com> > To: "Summer Long" <slong at redhat.com> > Cc: "Anne Gentle" <anne at openstack.org>, openstack-docs at lists.openstack.org > Sent: Monday, May 5, 2014 2:35:19 PM > Subject: Re: [Openstack-docs] time to Branch for icehouse? > > On 05/05/2014 02:59 AM, Summer Long wrote: > > Have a couple of patches on review I'd like to include first? Got caught > > out by the 'term=value' spacing issue. > > > > We can backport as usual ;) > > But yeah, let's see what we can get reviewed quickly, > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > From aj at suse.com Wed May 7 12:34:25 2014 From: aj at suse.com (Andreas Jaeger) Date: Wed, 07 May 2014 14:34:25 +0200 Subject: [Openstack-docs] time to Branch for icehouse? In-Reply-To: <718121345.3429152.1399463832116.JavaMail.zimbra@redhat.com> References: <5365133B.3010400@suse.com> <CAD0KtVERMv0_67M2Z+kaxyK5OpO-okkFs=ZgGe8whSzbJRCt=Q@mail.gmail.com> <5365860E.7020506@suse.com> <1879856974.225639.1399251589083.JavaMail.zimbra@redhat.com> <53671507.1040906@suse.com> <718121345.3429152.1399463832116.JavaMail.zimbra@redhat.com> Message-ID: <536A2851.6040602@suse.com> On 05/07/2014 01:57 PM, Summer Long wrote: > Apologies, have stalled out on bugs, but am not sure on timing anyway. > Andreas, did you already branch the Config Ref? Anne needs to branch - and this has not happened yet, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Wed May 7 16:16:48 2014 From: anne at openstack.org (Anne Gentle) Date: Wed, 7 May 2014 09:16:48 -0700 Subject: [Openstack-docs] =?utf-8?b?W0RvY10gW2NlaWxvbWV0ZXJdIFtjaW5kZXJd?= =?utf-8?b?IFtnbGFuY2VdIFtoZWF0XSBbaG9yaXpvbl0gW2tleXN0b25lXSBbbmV1?= =?utf-8?q?tron=5D_=5Bnova=5D_=5Bswift=5D_=5Btrove=5D_Atlanta_Summi?= =?utf-8?q?t_=E2=80=93_Discuss_docs_process_and_tool_improvements?= Message-ID: <CAD0KtVGzg367fV8QjvBUA5GXjaa4vcri2B0TB00AhiyaUmGdaA@mail.gmail.com> Hi all, Anne here - your friendly documentarian! As the docs PTL, it?s my job to gather input about and make doc tool and process decisions. This note is the first step: Your responses to this note give me input to share at the Summit where, hopefully, we will form a consensus about process and tool changes. About a week after the Summit, I'll produce a roadmap for changes that we will implement as a community. A recurring issue that I hope we can solve is barriers to doc contributions. Leading up to the Summit, I've gathered as much data as I can about these barriers. We have an awesome doc team and 20 core people on the team, but only about dozen people write and review the bulk of the cross-project documentation regularly. It's amazing we've accomplished all we have with the resources available. We have increased doc contributions by 10% since the last release, but even so, we must find ways to increase the doc contributor base. Remember three and a half years ago? We had nova and swift and a web site for each. Fast-forward and we now have docs for multiple audiences: - Contributors who make OpenStack - Deployers who configure OpenStack - Operations pros that run OpenStack - End users who consume and administer OpenStack But the docs? contributor base is not growing at the same rate as our audiences. Why not? The responses to my recent survey about doc contributions indicate that the top barriers to docs? contributions are: - Tools: DocBook and WADL are difficult - Doc locations: Lack of knowledge about where docs belong - Process: Git/gerrit as process - Subject-matter expertise: People do not have test environments and they feel that they don't know enough to contribute. Also, 70% of the respondents to the survey work on or consume OpenStack fewer than 10 hours a week. It's not easy to interpret and analyze this data, but I believe we're not facilitating part-time OpenStack users to write docs and feel confident in their contributions. To solve this problem, I want to explore possible changes to our doc tools and processes. We must engage more doc contributors to spread the doc creation and maintenance burden. Tuesday at 12:05 in B304, [1] we're having cross-project documentation session to discuss this list of requirements for doc tools and process changes: (See [2] for spreadsheet format.) Experience: Solution must be completely open source Content must be available online Search engines must be able to index Content must be searchable Content should be easily cross-linked by topic and type (priority: low) Enable comments, ratings, and analytics (or ask.openstack.org integration) (priority: low) Distribution: Readers must get versions of technical content specific to version of product Modular authoring of content Graphic and text content should be stored as files, not in a database Consumers must get technical content in PDF, html, video, and audio Workflow for review and approval prior to publishing content Authoring: Content must be re-usable across authors and personas (Single source) Must support many content authors with multiple authoring tools Existing content must migrate smoothly All content versions need to be comparable (diff) across versions Content must be organizationally segregated based on user personas Draft content must be reviewable in HTML Link maintenance - Links must update with little manual maintenance to avoid broken links and link validation I want to gather input about these requirements before we discuss implementation. As far as tools go, some possible solutions are Markdown, reStructuredText (RST), AsciiDoc, each with its own build framework. I'm not anticipating a complete migration, but we need to solve these barriers for certain docs. Please let me know your thoughts through the OpenStack-docs mailing list if you cannot attend in person. I am excited to hear your ideas, and I can't wait to meet a wider audience and serve more doc contributors. Thanks, Anne [1] http://junodesignsummit.sched.org/event/626a1e21babaf30d98973f5eb7402fcf [2] https://docs.google.com/spreadsheet/ccc?key=0AhXvn1h0dcyYdFNaQW1OaVNNejZzYlRMZjBnT0pLMVE&usp=sharing -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140507/99cf8a34/attachment.html> From mkassawara at gmail.com Wed May 7 19:15:42 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Wed, 7 May 2014 13:15:42 -0600 Subject: [Openstack-docs] =?utf-8?q?Atlanta_Summit_=E2=80=93_Patching_the_?= =?utf-8?q?documentation_process?= Message-ID: <CABA+jQpPPeiX0+_3kGPE1qE2YwCG=sMYf9OVe2+p1Bp42=dRgg@mail.gmail.com> On Thursday morning at 9:50 in room B301, we're holding a session [1] on how to improve the documentation process which includes the following topics: - Discuss creation of a new wiki page for documentation review guidelines and review the associated draft [2] - Discuss how to improve the new documentation contributors wiki page [3][4] - Discuss use of the installation guide as the standard for configurations, labels, etc. - Discuss use of an online style guide beyond our conventions - Discuss the discipline of submitting a bug and waiting for confirmation/triage/discussion/prioritization before uploading a patch Please refer to the associated Etherpad [5] for more details. [1] http://sched.co/1ik80Gn [2] https://wiki.openstack.org/wiki/Documentation/ReviewGuidelines [3] https://wiki.openstack.org/wiki/Documentation/HowTo<http://wiki.openstack.org/wiki/Documentation/HowTo/> [4] https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers [5] https://etherpad.openstack.org/p/summit0514-session-patching-the-docs-process Looking forward to seeing everyone at the summit! Matt -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140507/c15574f2/attachment.html> From rl at patchworkscience.org Wed May 7 20:43:38 2014 From: rl at patchworkscience.org (Roger Luethi) Date: Wed, 7 May 2014 22:43:38 +0200 Subject: [Openstack-docs] =?utf-8?b?W0RvY10gW2NlaWxvbWV0ZXJdIFtjaW5kZXJd?= =?utf-8?b?IFtnbGFuY2VdIFtoZWF0XSBbaG9yaXpvbl0gW2tleXN0b25lXSBbbmV1dHJv?= =?utf-8?b?bl0gW25vdmFdIFtzd2lmdF0gW3Ryb3ZlXSBBdGxhbnRhIFN1bW1pdCDigJMg?= =?utf-8?q?Discuss_docs_process_and_tool_improvements?= In-Reply-To: <CAD0KtVGzg367fV8QjvBUA5GXjaa4vcri2B0TB00AhiyaUmGdaA@mail.gmail.com> References: <CAD0KtVGzg367fV8QjvBUA5GXjaa4vcri2B0TB00AhiyaUmGdaA@mail.gmail.com> Message-ID: <20140507204338.GA22118@hellgate.ch> On Wed, 07 May 2014 09:16:48 -0700, Anne Gentle wrote: > Why not? The responses to my recent survey about doc contributions indicate > that the top barriers to docs? contributions are: > > - Tools: DocBook and WADL are difficult DocBook may be a pain to set up, but editing DocBook documents is hardly more difficult than Markdown, RST or any other solution will be by the time you have added all the features you want to have. Formatting docs is hard because the style guides demand that numerous rules be considered. Ditching DocBook won't change that. > - Subject-matter expertise: People do not have test environments and they > feel that they don't know enough to contribute. Also, 70% of the > respondents to the survey work on or consume OpenStack fewer than 10 hours > a week. The people who are qualified to contribute to the docs are usually not non-technical people, but they can't spend hours setting up an environment just to work on docs. IMHO good documentation (or scripts, or VM downloads) that make it easy to create a complete, working environment for testing and building documentation would go a long way towards making contributions easier. Roger From berendt at b1-systems.de Thu May 8 16:06:34 2014 From: berendt at b1-systems.de (Christian Berendt) Date: Thu, 08 May 2014 18:06:34 +0200 Subject: [Openstack-docs] =?utf-8?b?W0RvY10gW2NlaWxvbWV0ZXJdIFtjaW5kZXJd?= =?utf-8?b?IFtnbGFuY2VdIFtoZWF0XSBbaG9yaXpvbl0gW2tleXN0b25lXSBbbmV1dHJv?= =?utf-8?b?bl0gW25vdmFdIFtzd2lmdF0gW3Ryb3ZlXSBBdGxhbnRhIFN1bW1pdCDigJMg?= =?utf-8?q?Discuss_docs_process_and_tool_improvements?= In-Reply-To: <20140507204338.GA22118@hellgate.ch> References: <CAD0KtVGzg367fV8QjvBUA5GXjaa4vcri2B0TB00AhiyaUmGdaA@mail.gmail.com> <20140507204338.GA22118@hellgate.ch> Message-ID: <536BAB8A.4020900@b1-systems.de> On 05/07/2014 10:43 PM, Roger Luethi wrote: > The people who are qualified to contribute to the docs are usually not > non-technical people, but they can't spend hours setting up an environment > just to work on docs. IMHO good documentation (or scripts, or VM downloads) > that make it easy to create a complete, working environment for testing and > building documentation would go a long way towards making contributions > easier. NOTE: The box will soon be available. I think it's a good idea to have an isolated virtual environment for testing and building the documentation. Just created an initial Vagrant box that can be used for testing and building the documentation inside a virtual system. It includes Maven and tox. All documentation repositories (+ openstack-doc-tools) are already pulled (located in /opt/working) and all Maven dependencies are downloaded. There are three scripts available (located in /usr/local/bin) to simplify some doings: * pull.sh: runs git pull in every repository * fetch.sh: runs mvn dependency:copy-dependencies in every directory including a pom.xml * build.sh: builds a specified document in a specified repository For example to build the document admin-guide-cloud in the repository openstack-manuals run build.sh openstack-manuals admin-guide-cloud. The box has a directory "/opt/working" that's synced to the local directory working on the workstation. This way it's possible to edit and commit the files using the already available toolchain on the workstation and to test and build the documents inside the virtual system. As a nit port 8080 on the workstation is forwarded to port 80 on the virtual system. Port 80 simply serves the files located in /opt/working using Nginx. To view the local-files.html simply go to http://localhost:8080/openstack-manuals/doc/. Christian. -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 From berendt at b1-systems.de Thu May 8 16:08:42 2014 From: berendt at b1-systems.de (Christian Berendt) Date: Thu, 08 May 2014 18:08:42 +0200 Subject: [Openstack-docs] =?utf-8?b?W0RvY10gW2NlaWxvbWV0ZXJdIFtjaW5kZXJd?= =?utf-8?b?IFtnbGFuY2VdIFtoZWF0XSBbaG9yaXpvbl0gW2tleXN0b25lXSBbbmV1dHJv?= =?utf-8?b?bl0gW25vdmFdIFtzd2lmdF0gW3Ryb3ZlXSBBdGxhbnRhIFN1bW1pdCDigJMg?= =?utf-8?q?Discuss_docs_process_and_tool_improvements?= In-Reply-To: <536BAB8A.4020900@b1-systems.de> References: <CAD0KtVGzg367fV8QjvBUA5GXjaa4vcri2B0TB00AhiyaUmGdaA@mail.gmail.com> <20140507204338.GA22118@hellgate.ch> <536BAB8A.4020900@b1-systems.de> Message-ID: <536BAC0A.3030903@b1-systems.de> On 05/08/2014 06:06 PM, Christian Berendt wrote: > NOTE: The box will soon be available. Opened a review request for openstack-doc-tools: https://review.openstack.org/#/c/92867/ -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 From anne at openstack.org Thu May 8 16:42:02 2014 From: anne at openstack.org (Anne Gentle) Date: Thu, 8 May 2014 09:42:02 -0700 Subject: [Openstack-docs] =?utf-8?b?W0RvY10gW2NlaWxvbWV0ZXJdIFtjaW5kZXJd?= =?utf-8?b?IFtnbGFuY2VdIFtoZWF0XSBbaG9yaXpvbl0gW2tleXN0b25lXSBbbmV1?= =?utf-8?q?tron=5D_=5Bnova=5D_=5Bswift=5D_=5Btrove=5D_Atlanta_Summi?= =?utf-8?q?t_=E2=80=93_Discuss_docs_process_and_tool_improvements?= In-Reply-To: <20140507204338.GA22118@hellgate.ch> References: <CAD0KtVGzg367fV8QjvBUA5GXjaa4vcri2B0TB00AhiyaUmGdaA@mail.gmail.com> <20140507204338.GA22118@hellgate.ch> Message-ID: <CAD0KtVHkSuHxj6C2asf7e-gbaKvcygGFEnEtVDnai_5pqhdSCA@mail.gmail.com> On Wed, May 7, 2014 at 1:43 PM, Roger Luethi <rl at patchworkscience.org>wrote: > On Wed, 07 May 2014 09:16:48 -0700, Anne Gentle wrote: > > Why not? The responses to my recent survey about doc contributions > indicate > > that the top barriers to docs? contributions are: > > > > - Tools: DocBook and WADL are difficult > > DocBook may be a pain to set up, but editing DocBook documents is hardly > more difficult than Markdown, RST or any other solution will be by the time > you have added all the features you want to have. > Yep, I realize DocBook fulfills many if not all of the requirements, plus it's what's used within much of RedHat and we have a translation toolchain built for it. These are compelling except for the survey results indicating it's a barrier. I'd like to stick to discussion of the requirements. I just named two possible requirements, should those be included as well? Thanks for the input Roger, you're exactly who we're trying to reach out to for docs, and your input is super valuable. Anne > > Formatting docs is hard because the style guides demand that numerous > rules be considered. Ditching DocBook won't change that. > > > - Subject-matter expertise: People do not have test environments and they > > feel that they don't know enough to contribute. Also, 70% of the > > respondents to the survey work on or consume OpenStack fewer than 10 > hours > > a week. > > The people who are qualified to contribute to the docs are usually not > non-technical people, but they can't spend hours setting up an environment > just to work on docs. IMHO good documentation (or scripts, or VM downloads) > that make it easy to create a complete, working environment for testing and > building documentation would go a long way towards making contributions > easier. > > Roger > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140508/b4237916/attachment.html> From anne at openstack.org Thu May 8 17:05:44 2014 From: anne at openstack.org (Anne Gentle) Date: Thu, 8 May 2014 10:05:44 -0700 Subject: [Openstack-docs] =?utf-8?b?W0RvY10gW2NlaWxvbWV0ZXJdIFtjaW5kZXJd?= =?utf-8?b?IFtnbGFuY2VdIFtoZWF0XSBbaG9yaXpvbl0gW2tleXN0b25lXSBbbmV1?= =?utf-8?q?tron=5D_=5Bnova=5D_=5Bswift=5D_=5Btrove=5D_Atlanta_Summi?= =?utf-8?q?t_=E2=80=93_Discuss_docs_process_and_tool_improvements?= In-Reply-To: <536BAB8A.4020900@b1-systems.de> References: <CAD0KtVGzg367fV8QjvBUA5GXjaa4vcri2B0TB00AhiyaUmGdaA@mail.gmail.com> <20140507204338.GA22118@hellgate.ch> <536BAB8A.4020900@b1-systems.de> Message-ID: <CAD0KtVEO8zsv9b2-97a8pFbvS35qamoNa3YrNof+DhF8k_tJbQ@mail.gmail.com> On Thu, May 8, 2014 at 9:06 AM, Christian Berendt <berendt at b1-systems.de>wrote: > On 05/07/2014 10:43 PM, Roger Luethi wrote: > >> The people who are qualified to contribute to the docs are usually not >> non-technical people, but they can't spend hours setting up an environment >> just to work on docs. IMHO good documentation (or scripts, or VM >> downloads) >> that make it easy to create a complete, working environment for testing >> and >> building documentation would go a long way towards making contributions >> easier. >> > > NOTE: The box will soon be available. > > I think it's a good idea to have an isolated virtual environment for > testing and building the documentation. > I think this is cool, but to give an idea of some of the comments, I think people are having trouble testing OpenStack itself to make sure the docs are accurate. Examples: "Not sure I have the appropriate expertise." "...while I know how a system should be *configured*, I know little about the *install* process." "...it's often so much work to get a proper patch in because there are often so many calls that need to be made just to get to the point of where you want to make the fix. e.g. To create a Neutron port you first need to create a Net and then a Subnet and there are ton of little bits of info necessary for those calls. It becomes a non-starter, when you're strapped for time. The problem is intrinsic to deep APIs so I've got no idea what could help here." Also, to clarify, I believe there's more hesitation and doubt around WADL than DocBook echoed in the survey. I love this idea of a vagrant box for building docs though, will review! Thanks, Anne > > Just created an initial Vagrant box that can be used for testing and > building the documentation inside a virtual system. > > It includes Maven and tox. All documentation repositories (+ > openstack-doc-tools) are already pulled (located in /opt/working) and all > Maven dependencies are downloaded. > > There are three scripts available (located in /usr/local/bin) to simplify > some doings: > > * pull.sh: runs git pull in every repository > * fetch.sh: runs mvn dependency:copy-dependencies in every directory > including a pom.xml > * build.sh: builds a specified document in a specified repository > > For example to build the document admin-guide-cloud in the repository > openstack-manuals run build.sh openstack-manuals admin-guide-cloud. > > The box has a directory "/opt/working" that's synced to the local > directory working on the workstation. This way it's possible to edit and > commit the files using the already available toolchain on the workstation > and to test and build the documents inside the virtual system. > > As a nit port 8080 on the workstation is forwarded to port 80 on the > virtual system. Port 80 simply serves the files located in /opt/working > using Nginx. To view the local-files.html simply go to > http://localhost:8080/openstack-manuals/doc/. > > Christian. > > -- > Christian Berendt > Cloud Computing Solution Architect > Mail: berendt at b1-systems.de > > B1 Systems GmbH > Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de > GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140508/51b20b14/attachment.html> From shaunm at gnome.org Fri May 9 15:47:33 2014 From: shaunm at gnome.org (Shaun McCance) Date: Fri, 09 May 2014 11:47:33 -0400 Subject: [Openstack-docs] [Openstack-i18n] Switch to itstool for docs translation? In-Reply-To: <53662589.2090504@suse.com> References: <1399121582.24585.10.camel@verso> <53662589.2090504@suse.com> Message-ID: <1399650453.2275.131.camel@recto> On Sun, 2014-05-04 at 13:33 +0200, Andreas Jaeger wrote: > On 05/03/2014 02:53 PM, Shaun McCance wrote: > > Hi all, > > > > I've been working on switching the docs translation infrastructure over > > to itstool. This affects openstack-manuals, operations-guide, and > > api-site. The current tools are based on xml2po, but they don't call > > xml2po directly. Instead, they import xml2po and mess around with its > > internals to get some custom behavior. > > > > itstool is designed to handle custom behavior with rules from the W3C > > Internationalization Tag Set (ITS). You can see the ITS I put together > > so far here: > > > > https://review.openstack.org/#/c/91869/3/os_doc_tools/resources/openstack.its,unified > > > > Using ITS also allows us to do local ITS attributes to override the > > behavior for specific elements. See a simple example here: > > > > https://review.openstack.org/#/c/91872/1/api-quick-start/src/docbkx/api-quick-start-intro.xml,unified > > > > Most messages in the PO files will be the same. The one big difference > > will be in how placeholders are done when there's a block-level element > > inside a block-level element (a practice I discourage anyway). > > Could you give an example, please? In the user-guide, in section_dashboard_manage_images.xml, there's an itemizedlist inside a para. An itemizedlist is a block-level element, so it starts one or more new PO messages. The message for the para gets a placeholder element so translators know it's there, and can move it around if necessary. With xml2po, it looks like this: #: doc/user-guide/section_dashboard_manage_images.xml:179(para) msgid "" "In the Update Image dialog box, you can perform the following " "actions: <placeholder-1/>" msgstr "" With itstool, it looks like this: #. (itstool) path: step/para #: doc/user-guide/section_dashboard_manage_images.xml:179 msgid "" "In the Update Image dialog box, you can perform the following " "actions: <_:itemizedlist-1/>" msgstr "" itstool puts all its special elements in a namespace using the _ prefix. (It gets mapped to an internal namespace URI during processing.) This helps prevent conflicts, and it allows the local name of the placeholder element to reflect what kind of thing gets put there, which is helpful. > > I'd like to get input from translators, as well as any other docs folks > > who've worked on this. Most of the document translations are incomplete > > anyway, but it would nevertheless be best to do this at the beginning of > > a release cycle. > > I assume that we can convert the existing translated files in such a way > that we do not loose translations? How to do this properly? Download > current files from transifex, convert into new format, upload converted > files - and then continue translating? Or will it be enough to upload > the pot file and let transfix do the translation? Any translations where the source string is the same will just continue to work. That's the way PO works. I looked into migrating obvious things like the placeholder difference. There are very few translations though. I could maybe fix up 20-30 across all translations of all books. There isn't anything else to migrate. > Did you test a conversation of locale files and reconstructed translated > manuals? Is this just working with the updated tools or are additional > steps needed? Yes. My patch includes also using itstool for generating the DocBook from the PO files. I tested it. It works. > I think we need to ensure with the infra team that itstools are > installed on our machines. That's the big question I haven't been able to answer yet. Preferably at least version 2.0.1. > I see that some patches are dependent on each other and we need to do > certain steps in a specific order. Is this something you can write down > as plan, please? I did write this: https://wiki.openstack.org/wiki/Documentation/Translation#ItsTool_Conversion It has steps that need to be done (roughly) in order. -- Shaun From aj at suse.com Fri May 9 15:57:40 2014 From: aj at suse.com (Andreas Jaeger) Date: Fri, 09 May 2014 17:57:40 +0200 Subject: [Openstack-docs] [Openstack-i18n] Switch to itstool for docs translation? In-Reply-To: <1399650453.2275.131.camel@recto> References: <1399121582.24585.10.camel@verso> <53662589.2090504@suse.com> <1399650453.2275.131.camel@recto> Message-ID: <536CFAF4.2010006@suse.com> On 05/09/2014 05:47 PM, Shaun McCance wrote: > [...] >> I think we need to ensure with the infra team that itstools are >> installed on our machines. > > That's the big question I haven't been able to answer yet. Preferably at > least version 2.0.1. Just talked briefly with the infra team and checked our setup: What is in Ubuntu Precise? I assume the package is not installed but if it's available, we can add rules to the gate machines to have it installed... Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Fri May 9 16:04:41 2014 From: aj at suse.com (Andreas Jaeger) Date: Fri, 09 May 2014 18:04:41 +0200 Subject: [Openstack-docs] [Openstack-i18n] Switch to itstool for docs translation? In-Reply-To: <536CFAF4.2010006@suse.com> References: <1399121582.24585.10.camel@verso> <53662589.2090504@suse.com> <1399650453.2275.131.camel@recto> <536CFAF4.2010006@suse.com> Message-ID: <536CFC99.2040205@suse.com> On 05/09/2014 05:57 PM, Andreas Jaeger wrote: > On 05/09/2014 05:47 PM, Shaun McCance wrote: >> [...] > >>> I think we need to ensure with the infra team that itstools are >>> installed on our machines. >> >> That's the big question I haven't been able to answer yet. Preferably at >> least version 2.0.1. > > Just talked briefly with the infra team and checked our setup: > > What is in Ubuntu Precise? I assume the package is not installed but if > it's available, we can add rules to the gate machines to have it > installed... Shaun, this is in precise: http://packages.ubuntu.com/precise/itstool This is a python package, isn't it? Get 2.0.1 on pypi.python.org and we can install it from there... Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Fri May 9 20:30:13 2014 From: anne at openstack.org (Anne Gentle) Date: Fri, 9 May 2014 15:30:13 -0500 Subject: [Openstack-docs] stable/icehouse branch for openstack-manuals Message-ID: <CAD0KtVH=_m1KwPLhzFvnZS=Wq=YuViNAC8QOMO-r3Yo0dnpAnQ@mail.gmail.com> Hi all, Congrats on the docs release for the Install Guides and Configuration Reference! Huge appreciation vibes to everyone who made the Icehouse release a success for docs. I'm continually grateful for the great group we have working on docs and doc tools. What this means is: - If you have a patch to the install-guide or config-ref files and it affects Icehouse also, in the commit message put "backport: stable/icehouse" so that reviewers know what needs to go to the stable/icehouse branch. - We can now begin documenting Juno changes in those documents. As noted previously, every other document is continuously published, meaning, if a patch is approved, it will be published live. Thanks again, and I hope to see you all in Atlanta. Anne -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140509/b48a81d8/attachment.html> From aj at suse.com Fri May 9 21:08:47 2014 From: aj at suse.com (Andreas Jaeger) Date: Fri, 09 May 2014 23:08:47 +0200 Subject: [Openstack-docs] stable/icehouse branch for openstack-manuals In-Reply-To: <CAD0KtVH=_m1KwPLhzFvnZS=Wq=YuViNAC8QOMO-r3Yo0dnpAnQ@mail.gmail.com> References: <CAD0KtVH=_m1KwPLhzFvnZS=Wq=YuViNAC8QOMO-r3Yo0dnpAnQ@mail.gmail.com> Message-ID: <536D43DF.6070507@suse.com> On 05/09/2014 10:30 PM, Anne Gentle wrote: > Hi all, > > Congrats on the docs release for the Install Guides and Configuration > Reference! Huge appreciation vibes to everyone who made the Icehouse > release a success for docs. I'm continually grateful for the great group > we have working on docs and doc tools. > > What this means is: > - If you have a patch to the install-guide or config-ref files and it > affects Icehouse also, in the commit message put "backport: > stable/icehouse" so that reviewers know what needs to go to the > stable/icehouse branch. > - We can now begin documenting Juno changes in those documents. > > As noted previously, every other document is continuously published, > meaning, if a patch is approved, it will be published live. > > Thanks again, and I hope to see you all in Atlanta. Just noticed that our jobs do not handle icehouse properly - I hope this fixed it: https://review.openstack.org/93129 And we need this patch in our branch for building: https://review.openstack.org/#/c/93124/ I'll push these forward myself and suggest that for now no patches for stable/icehouse get approved until we've verified that everything works. If you look at 93124, you see that the Install Guide and Config Reference have file names with trunk in it - they should have stable/icehouse. Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Sat May 10 06:58:57 2014 From: aj at suse.com (Andreas Jaeger) Date: Sat, 10 May 2014 08:58:57 +0200 Subject: [Openstack-docs] stable/icehouse branch for openstack-manuals In-Reply-To: <536D43DF.6070507@suse.com> References: <CAD0KtVH=_m1KwPLhzFvnZS=Wq=YuViNAC8QOMO-r3Yo0dnpAnQ@mail.gmail.com> <536D43DF.6070507@suse.com> Message-ID: <536DCE31.10701@suse.com> On 05/09/2014 11:08 PM, Andreas Jaeger wrote: > On 05/09/2014 10:30 PM, Anne Gentle wrote: >> Hi all, >> >> Congrats on the docs release for the Install Guides and Configuration >> Reference! Huge appreciation vibes to everyone who made the Icehouse >> release a success for docs. I'm continually grateful for the great group >> we have working on docs and doc tools. >> >> What this means is: >> - If you have a patch to the install-guide or config-ref files and it >> affects Icehouse also, in the commit message put "backport: >> stable/icehouse" so that reviewers know what needs to go to the >> stable/icehouse branch. >> - We can now begin documenting Juno changes in those documents. >> >> As noted previously, every other document is continuously published, >> meaning, if a patch is approved, it will be published live. >> >> Thanks again, and I hope to see you all in Atlanta. > > Just noticed that our jobs do not handle icehouse properly - I hope this > fixed it: > https://review.openstack.org/93129 This breaks all gate jobs now ;( I'm sorry, Andreas > And we need this patch in our branch for building: > https://review.openstack.org/#/c/93124/ > > I'll push these forward myself and suggest that for now no patches for > stable/icehouse get approved until we've verified that everything works. > > If you look at 93124, you see that the Install Guide and Config > Reference have file names with trunk in it - they should have > stable/icehouse. > > Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Sat May 10 11:27:41 2014 From: aj at suse.com (Andreas Jaeger) Date: Sat, 10 May 2014 13:27:41 +0200 Subject: [Openstack-docs] stable/icehouse branch for openstack-manuals In-Reply-To: <536DCE31.10701@suse.com> References: <CAD0KtVH=_m1KwPLhzFvnZS=Wq=YuViNAC8QOMO-r3Yo0dnpAnQ@mail.gmail.com> <536D43DF.6070507@suse.com> <536DCE31.10701@suse.com> Message-ID: <536E0D2D.5020706@suse.com> On 05/10/2014 08:58 AM, Andreas Jaeger wrote: > On 05/09/2014 11:08 PM, Andreas Jaeger wrote: >> On 05/09/2014 10:30 PM, Anne Gentle wrote: >>> Hi all, >>> >>> Congrats on the docs release for the Install Guides and Configuration >>> Reference! Huge appreciation vibes to everyone who made the Icehouse >>> release a success for docs. I'm continually grateful for the great group >>> we have working on docs and doc tools. >>> >>> What this means is: >>> - If you have a patch to the install-guide or config-ref files and it >>> affects Icehouse also, in the commit message put "backport: >>> stable/icehouse" so that reviewers know what needs to go to the >>> stable/icehouse branch. >>> - We can now begin documenting Juno changes in those documents. >>> >>> As noted previously, every other document is continuously published, >>> meaning, if a patch is approved, it will be published live. >>> >>> Thanks again, and I hope to see you all in Atlanta. >> >> Just noticed that our jobs do not handle icehouse properly - I hope this >> fixed it: >> https://review.openstack.org/93129 > > This breaks all gate jobs now ;( I'm sorry, The infra job was reverted (Clark was sleep walking ; - thanks!). The setup was broken on the havana branch as well. Fortunately, openstack-doc-test has an option to set the values manually that are read from the properties file and I've set these values now. I'm double checking these patches now and if they pass, will self-approve to unbreak the tree: https://review.openstack.org/93183 https://review.openstack.org/93182 Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Sat May 10 12:57:20 2014 From: aj at suse.com (Andreas Jaeger) Date: Sat, 10 May 2014 14:57:20 +0200 Subject: [Openstack-docs] stable/icehouse branch for openstack-manuals In-Reply-To: <536E0D2D.5020706@suse.com> References: <CAD0KtVH=_m1KwPLhzFvnZS=Wq=YuViNAC8QOMO-r3Yo0dnpAnQ@mail.gmail.com> <536D43DF.6070507@suse.com> <536DCE31.10701@suse.com> <536E0D2D.5020706@suse.com> Message-ID: <536E2230.1050204@suse.com> On 05/10/2014 01:27 PM, Andreas Jaeger wrote: > [...] > The infra job was reverted (Clark was sleep walking ; - thanks!). > > The setup was broken on the havana branch as well. Fortunately, > openstack-doc-test has an option to set the values manually that are > read from the properties file and I've set these values now. > > I'm double checking these patches now and if they pass, will > self-approve to unbreak the tree: > https://review.openstack.org/93183 > https://review.openstack.org/93182 > > Andreas Everything looks fine to me now - feel free to use the Icehouse branch ;) Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Sun May 11 19:16:08 2014 From: aj at suse.com (Andreas Jaeger) Date: Sun, 11 May 2014 21:16:08 +0200 Subject: [Openstack-docs] Unused files in openstack-manuals - please check them In-Reply-To: <53458FCC.9080200@suse.com> References: <53458FCC.9080200@suse.com> Message-ID: <536FCC78.5010400@suse.com> On 04/09/2014 08:22 PM, Andreas Jaeger wrote: > I've just send a couple of patches to remove or include currently unused > files. With the patches I'm going to submit, once I have network again, these files remain as orphaned files (besides the training guide): common/section_cli_keystone_apiv3.xml common/section_cli_keystone_credentials.xml common/section_cli_nova_fileinjection.xml common/section_cli_nova_metadata.xml common/section_cli_nova_secgroups.xml common/section_cli_nova_sshkeys.xml common/section_dashboard_launch_instances_from_image.xml common/section_keystone_db_sync.xml common/section_user-data.xml common/section_using-vnc-console.xml Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Mon May 12 18:22:06 2014 From: anne at openstack.org (Anne Gentle) Date: Mon, 12 May 2014 13:22:06 -0500 Subject: [Openstack-docs] Input at the Summit on Disqus comments Message-ID: <CAD0KtVHbysXnMA3FNGZDP2hmz-jTJE=z7cmOieqp0QGKU6GrsA@mail.gmail.com> Hi all, Today after one of the Ops discussions I had a conversation with a sysadmin who really misses the Disqus comments, and doesn't think the link to ask.openstack.org offers enough context that a doc page offers. I told him we really wanted the widget from ask that we could embed like Disqus comments, he said that would be better. Just wanting to let us all know one bit of input on turning off comments. I'm not wanting to reverse the decision, just letting us know that we have some input that there's a sense of loss of context. For Icehouse, only the install guide has comments turned on, and I had logged a bug last week asking for those to be turned off. Andreas has a patch ready at https://review.openstack.org/#/c/93280 and I just wanted to make sure we are in tune once this change happens so that we can offer lots of doc links and context on ask.openstack.org. Also, if anyone is interested in coding the widget for ask.openstack.orgthat could be embedded, please let me connect you! It seems like it would be a real win. Thanks, Anne -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140512/33581f21/attachment.html> From gauvain.pocentek at objectif-libre.com Tue May 13 19:28:40 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Tue, 13 May 2014 21:28:40 +0200 Subject: [Openstack-docs] config-ref blueprints Message-ID: <aa24a26606361e5b56dff02f12092112@objectif-libre.com> Hello guys, I've drafted a couple blueprints for the config ref, I'd like to hear some feedback. A live discussion at the summit would be nice but I wanted to include everyone in the loop. [1] deals with the fact that we don't have a single page listing all available options for each OS project (AFAIK). For [2] the idea is to improve the documentation about options common to all the projects, but also avoid duplication. Thanks, Gauvain [1]: https://blueprints.launchpad.net/openstack-manuals/+spec/config-ref-all-options-table [2]: https://blueprints.launchpad.net/openstack-manuals/+spec/config-ref-common-sections From anne at openstack.org Tue May 13 21:41:35 2014 From: anne at openstack.org (Anne Gentle) Date: Tue, 13 May 2014 16:41:35 -0500 Subject: [Openstack-docs] config-ref blueprints In-Reply-To: <aa24a26606361e5b56dff02f12092112@objectif-libre.com> References: <aa24a26606361e5b56dff02f12092112@objectif-libre.com> Message-ID: <CAD0KtVHp+270xOEo=MkvaF6KjVZZeRFA4wntn3GAK=f+NKgBsQ@mail.gmail.com> On Tue, May 13, 2014 at 2:28 PM, Gauvain Pocentek < gauvain.pocentek at objectif-libre.com> wrote: > Hello guys, > > I've drafted a couple blueprints for the config ref, I'd like to hear some > feedback. A live discussion at the summit would be nice but I wanted to > include everyone in the loop. > > [1] deals with the fact that we don't have a single page listing all > available options for each OS project (AFAIK). > Do you have a request from the community for this single page listing? I am not getting this type of input informally so I am not sure where this request comes from. > > For [2] the idea is to improve the documentation about options common to > all the projects, but also avoid duplication. > I think avoiding duplication is a good goal here. A higher priority request to me, that I've gotten from various conversations, is that the reference listing is great, but the more requested next document is for combinations of configurations for a particular goal in mind. I think some of this type of documentation may come out of the design guide book sprint, but I'd also like us to think about how we might write this type of documentation. Thanks Gauvain for brining this to the list! Anne > > Thanks, > Gauvain > > [1]: https://blueprints.launchpad.net/openstack-manuals/+spec/ > config-ref-all-options-table > [2]: https://blueprints.launchpad.net/openstack-manuals/+spec/ > config-ref-common-sections > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140513/eb8a2a7d/attachment.html> From gauvain.pocentek at objectif-libre.com Tue May 13 22:08:26 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Wed, 14 May 2014 00:08:26 +0200 Subject: [Openstack-docs] config-ref blueprints In-Reply-To: <CAD0KtVHp+270xOEo=MkvaF6KjVZZeRFA4wntn3GAK=f+NKgBsQ@mail.gmail.com> References: <aa24a26606361e5b56dff02f12092112@objectif-libre.com> <CAD0KtVHp+270xOEo=MkvaF6KjVZZeRFA4wntn3GAK=f+NKgBsQ@mail.gmail.com> Message-ID: <7f49b7c31f1312b15d03501c7ba63eea@objectif-libre.com> Le 2014-05-13 23:41, Anne Gentle a ?crit?: > On Tue, May 13, 2014 at 2:28 PM, Gauvain Pocentek > <gauvain.pocentek at objectif-libre.com> wrote: > >> Hello guys, >> >> I've drafted a couple blueprints for the config ref, I'd like to hear >> some feedback. A live discussion at the summit would be nice but I >> wanted to include everyone in the loop. >> >> [1] deals with the fact that we don't have a single page listing all >> available options for each OS project (AFAIK). > > Do you have a request from the community for this single page > listing? I am not getting this type of input informally so I am not > sure where this request comes from. I don't think we've had a request from the community. But we discussed this kind of changes a while ago (http://lists.openstack.org/pipermail/openstack-docs/2014-March/004036.html). >> For [2] the idea is to improve the documentation about options common >> to all the projects, but also avoid duplication. > > I think avoiding duplication is a good goal here.? > > A higher priority request to me, that I've gotten from various > conversations, is that the reference listing is great, but the more > requested next document is for combinations of configurations for a > particular goal in mind. I think some of this type of documentation > may come out of the design guide book sprint, but I'd also like us to > think about how we might write this type of documentation. Some kind of configuration cookbook? I like the idea :) Isn't that something that would better be sitting in the Cloud Admin Guide rather than the config-ref? Either way it's something that would probably be very useful to users, and that would match the idea behind the spec (how do I use Qpid/Rabbit? How do I use keystone token authentication?). > > Thanks Gauvain for brining this to the list! Thanks for your answer :) Gauvain From anne at openstack.org Wed May 14 18:24:46 2014 From: anne at openstack.org (Anne Gentle) Date: Wed, 14 May 2014 13:24:46 -0500 Subject: [Openstack-docs] Documentation Pod at the Summit Message-ID: <CAD0KtVFRaHrf2G8eLTTvc_+HEvH-kixS4fh6degJQPtuMpUHcg@mail.gmail.com> Hi all, If you're in Atlanta for the Design Summit, I wanted to be sure you know about the Documentation Pod downstairs from the developer's lounge. It's pod 12 in room 204. Thanks, Anne -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140514/c45c9b41/attachment.html> From aj at suse.com Thu May 15 11:02:57 2014 From: aj at suse.com (Andreas Jaeger) Date: Thu, 15 May 2014 07:02:57 -0400 Subject: [Openstack-docs] [Openstack-i18n] Switch to itstool for docs translation? In-Reply-To: <1399121582.24585.10.camel@verso> References: <1399121582.24585.10.camel@verso> Message-ID: <53749EE1.105@suse.com> I discussed this a bit with Daisy and Akihiro at the summit and both need some more investigation on this. Let me re-share some pointers for all here. I suggest that some of you translators have a look at patch 90766 and this thread and figure out whether there are any problems. This move to itstools is a move to newer and maintained tools that will simplify our live on the tools side. It only affects docs translation - the manuals - and not the core projects. So, this is related to all the resources you find on transifex under openstack-manuals. I'd like to see this happen because of the improvements it brings, so please evaluate it and speak up if you see problems - a "go ahead" would be also appreciated. Note that Daisy needs to approve the blue print before this will go in. Patch set 1 of patch https://review.openstack.org/#/c/90766/ shows the changes to the locale files, for example: https://review.openstack.org/#/c/90766/1/doc/user-guide-admin/locale/en_AU.po These patches show what can be done with the tools - marking some sections as non-translatable (and thus not show up in transifex) sounds like a great idea to me: https://review.openstack.org/#/c/91873/ https://review.openstack.org/#/c/91872/ The conversation of the code is shown here: https://review.openstack.org/#/c/91869/ Especially this patch is interesting, it shows how easy it is to filter out what gets translated and what not: https://review.openstack.org/#/c/91869/3/os_doc_tools/resources/openstack.its https://blueprints.launchpad.net/openstack-manuals/+spec/itstool-for-docs Full specification: https://wiki.openstack.org/wiki/Documentation/Translation#ItsTool_Conversion Shaun, for using itstool on the infra machines, we really need to have it on pypi. Can you make this happen, please? Also, please add to the commit message of each of your patches: blueprint itstool-for-docs Thanks, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Thu May 15 12:41:51 2014 From: anne at openstack.org (Anne Gentle) Date: Thu, 15 May 2014 07:41:51 -0500 Subject: [Openstack-docs] What's Up Doc - Atlanta Summit edition Message-ID: <CAD0KtVGj5q-sKXn5xELFwOxLDFZ7nR0HpD4bu0vR8biv7XX55Q@mail.gmail.com> Hi all from Atlanta where we have over 4,000 gathered to collaborate in person! I'm enjoying the week immensely. My favorite so far has to be the Women of OpenStack gathering last night. We are onto something cool in this community. Tuesday we had two sessions about cross-project documentation and though Nick was worried there would be overlap, we got great input from each quite different from the other. My takeaway is that the developers are very happy to hand doc tasks over to "real" writers but that they can help us with the specs, with excellent commit messages, and we want to follow the specs lead by making an excellent template for commit messages and continue to spread the word about DocImpact. [1] For the cross-project session about requirements for our tooling, one takeaway is that we won't fix what isn't broken. [2] Also, even if for some books we discontinue the use of DocBook, places like RedHat will still figure out how to use the upstream documentation and continue to improve it. I really want to emphasize a shift to end-user docs this release. We created developer.openstack.org this past release, and I want to see how we can build out more end-user content for application developers. I've been in many of the CLI and SDK tracks and thinking hard about how to make the best deliverables we can. Please offer input if you're interested! I'm also going to write a roadmap for each document -- and though yesterday I said I'd put those on the wiki, I think I'll put a roadmap file in with each document. Then anyone who wants to figure out where the book stands and what they might do to work on it that's high priority, they can. The Install Guide session went well yesterday and one decision we came to after much discussion was to standardize on manual updates of the config files rather than hiding them behind openstack-config commands. Matt has a great summary in the Etherpad for the session on the tasks for the next release. [3] I've also been talking to Ironic team about how to document their installation process and while in the session on Install we did not have anyone who wanted bare metal in that guide, it may make sense to put a chapter about why you would use a project like Ironic for installation in the Cloud Admin Guide. I'd love input on where that fits in our current documentation set. I also have to share a great comment from the User Survey [4] that Tim Bell is especially delighted with because he knows how disappointed people were in the docs 18 months ago, even 12 months ago. "Over the last 6 months I think the documentation has improved significantly. I have seen others recently hold up OpenStack docs as a model to strive for." We are making a difference across the world and our hard work is paying off. Thanks to all of you who are a part of this effort -- nearly 200 of us this last six months. I can't express enough how grateful I am to have such dedication shine through in OpenStack docs. Today we have "Patching the documentation process" at 9:50. Tomorrow we'll talk about Continuous publishing and automation at 9:00, and discuss how to Beef up User and Ops Guides for integrated projects at 11:40. Lots more work to do, let's tackle this! Anne 1. https://etherpad.openstack.org/p/easier_documentation_for_developers 2. https://etherpad.openstack.org/p/summit-session-cross-project-docs 3. https://etherpad.openstack.org/p/installation-guide-audit 4. http://www.slideshare.net/ryan-lane/openstack-atlanta-user-survey slide 24 -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140515/f8cc874b/attachment.html> From gauvain.pocentek at objectif-libre.com Thu May 15 15:34:04 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Thu, 15 May 2014 17:34:04 +0200 Subject: [Openstack-docs] [Heat][Documentation] Heat template documentation Message-ID: <90d4482bcd0b7a52c7262631ffd3baef@objectif-libre.com> Hello, This mail probably mainly concerns the doc team, but I guess that the heat team wants to know what's going on. We've shortly discussed the state of heat documentation with Anne Gentle and Andreas Jaeger yesterday, and I'd like to share what we think would be nice to do. Currently we only have a small section in the user guide that describes how to start a stack, but nothing documenting how to write templates. The heat developer doc provides a good reference, but I think it's not easy to use to get started. So the idea is to add an "OpenStack Orchestration" chapter in the user guide that would document how to use a cloud with heat, and how to write templates. I've drafted a spec to keep track of this at [0]. Let me know if this sounds OK to you all. Gauvain Pocentek Objectif Libre - Infrastructure et Formations Linux http://www.objectif-libre.com [0]: https://blueprints.launchpad.net/openstack-manuals/+spec/heat-templates From gauvain.pocentek at objectif-libre.com Thu May 15 15:40:40 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Thu, 15 May 2014 17:40:40 +0200 Subject: [Openstack-docs] Policy for approving backports Message-ID: <e8ae767f5c80279bb44a1507828e3116@objectif-libre.com> Hello, I guess I should have asked this during this morning's doc session at the summit, but I hadn't had real coffee yet (only decaf!). How do we handle backports reviews? Is one +2 enough (that's what Andreas used to do during the post havana backport storm)? Is self approval a valid option? I'd like to hear what you guys think. Thanks, Gauvain Pocentek Objectif Libre - Infrastructure et Formations Linux http://www.objectif-libre.com From tom at openstack.org Thu May 15 15:48:05 2014 From: tom at openstack.org (Tom Fifield) Date: Thu, 15 May 2014 11:48:05 -0400 Subject: [Openstack-docs] Policy for approving backports In-Reply-To: <e8ae767f5c80279bb44a1507828e3116@objectif-libre.com> References: <e8ae767f5c80279bb44a1507828e3116@objectif-libre.com> Message-ID: <5374E1B5.1090004@openstack.org> On 15/05/14 11:40, Gauvain Pocentek wrote: > Hello, > > I guess I should have asked this during this morning's doc session at > the summit, but I hadn't had real coffee yet (only decaf!). > > How do we handle backports reviews? Is one +2 enough (that's what > Andreas used to do during the post havana backport storm)? Is self > approval a valid option? > > I'd like to hear what you guys think. IMO: one sanity-check +2 from someone who is not the submitter From gauvain.pocentek at objectif-libre.com Thu May 15 15:54:27 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Thu, 15 May 2014 17:54:27 +0200 Subject: [Openstack-docs] [Heat][Documentation] Heat template documentation In-Reply-To: <90d4482bcd0b7a52c7262631ffd3baef@objectif-libre.com> References: <90d4482bcd0b7a52c7262631ffd3baef@objectif-libre.com> Message-ID: <aacbfe99975184407bffdd75638e7171@objectif-libre.com> (Resending to add openstack-dev) Gauvain Pocentek Objectif Libre - Infrastructure et Formations Linux http://www.objectif-libre.com Le 2014-05-15 17:34, Gauvain Pocentek a ?crit?: > Hello, > > This mail probably mainly concerns the doc team, but I guess that the > heat team wants to know what's going on. > > We've shortly discussed the state of heat documentation with Anne > Gentle and Andreas Jaeger yesterday, and I'd like to share what we > think would be nice to do. > > Currently we only have a small section in the user guide that > describes how to start a stack, but nothing documenting how to write > templates. The heat developer doc provides a good reference, but I > think it's not easy to use to get started. > > So the idea is to add an "OpenStack Orchestration" chapter in the > user guide that would document how to use a cloud with heat, and how > to write templates. > > I've drafted a spec to keep track of this at [0]. > > Let me know if this sounds OK to you all. > > Gauvain Pocentek > > Objectif Libre - Infrastructure et Formations Linux > http://www.objectif-libre.com > > [0]: > https://blueprints.launchpad.net/openstack-manuals/+spec/heat-templates > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs From aj at suse.com Thu May 15 16:08:28 2014 From: aj at suse.com (Andreas Jaeger) Date: Thu, 15 May 2014 12:08:28 -0400 Subject: [Openstack-docs] Policy for approving backports In-Reply-To: <5374E1B5.1090004@openstack.org> References: <e8ae767f5c80279bb44a1507828e3116@objectif-libre.com> <5374E1B5.1090004@openstack.org> Message-ID: <5374E67C.40504@suse.com> On 05/15/2014 11:48 AM, Tom Fifield wrote: > On 15/05/14 11:40, Gauvain Pocentek wrote: >> Hello, >> >> I guess I should have asked this during this morning's doc session at >> the summit, but I hadn't had real coffee yet (only decaf!). >> >> How do we handle backports reviews? Is one +2 enough (that's what >> Andreas used to do during the post havana backport storm)? Is self >> approval a valid option? >> >> I'd like to hear what you guys think. > > IMO: one sanity-check +2 from someone who is not the submitter Agreed. Also, backports should not be edited, if there are problems noticed, we should do a patch for master to fix those and backport that one, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Thu May 15 20:49:19 2014 From: aj at suse.com (Andreas Jaeger) Date: Thu, 15 May 2014 16:49:19 -0400 Subject: [Openstack-docs] Translation gate for doc jobs Message-ID: <5375284F.3030208@suse.com> Inspired by some discussions here at the summit, I'd like to setup some translation gate for jobs. Patch https://review.openstack.org/93526 (merged) sets up a test that can be invoked with "tox -e checklang" which builds all "supported" manuals. I propose the following: * Setup checking/gating jobs that runs this test and mark it as non-voting. * Create policy on how to handle failures. Proposed policy: * We only gate on manual/language combinations that are translated sufficiently. Right now that's for openstack-manuals Japanese with the Security Guide, HA Guide and Install Guides only. * If an import from transifex fails, creates a failure, we do not approve the import. * If any other patch fails, the failure might get ignored. * In any case of failure, let's send an email to the openstack-i18n mailing list asking them to investigate and fix. What do you think? Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From tom at openstack.org Fri May 16 12:02:01 2014 From: tom at openstack.org (Tom Fifield) Date: Fri, 16 May 2014 08:02:01 -0400 Subject: [Openstack-docs] Translation gate for doc jobs In-Reply-To: <5375284F.3030208@suse.com> References: <5375284F.3030208@suse.com> Message-ID: <5375FE39.20904@openstack.org> On 15/05/14 16:49, Andreas Jaeger wrote: > Inspired by some discussions here at the summit, I'd like to setup some > translation gate for jobs. > > Patch https://review.openstack.org/93526 (merged) sets up a test that > can be invoked with "tox -e checklang" which builds all "supported" manuals. > > I propose the following: > > * Setup checking/gating jobs that runs this test and mark it as non-voting. > * Create policy on how to handle failures. > > Proposed policy: > * We only gate on manual/language combinations that are translated > sufficiently. Right now that's for openstack-manuals Japanese with the > Security Guide, HA Guide and Install Guides only. > * If an import from transifex fails, creates a failure, we do not > approve the import. > * If any other patch fails, the failure might get ignored. > * In any case of failure, let's send an email to the openstack-i18n > mailing list asking them to investigate and fix. > > What do you think? Good, but I'd prefer the creation of a bug in openstack-i18n on launchpad, instead of a mailing list post. This way people who are interested in fixing such things can get notified by email (through bug tracker subscriptions), and the mailing list is kept clear for people who just want to translate things and participate in the community in other ways :) From gauvain.pocentek at objectif-libre.com Fri May 16 14:05:31 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Fri, 16 May 2014 16:05:31 +0200 Subject: [Openstack-docs] Policy for approving backports In-Reply-To: <5374E67C.40504@suse.com> References: <e8ae767f5c80279bb44a1507828e3116@objectif-libre.com> <5374E1B5.1090004@openstack.org> <5374E67C.40504@suse.com> Message-ID: <fec80c3953ae843bbee513bd22d8a1c8@objectif-libre.com> Le 2014-05-15 18:08, Andreas Jaeger a ?crit?: > On 05/15/2014 11:48 AM, Tom Fifield wrote: >> On 15/05/14 11:40, Gauvain Pocentek wrote: >>> Hello, >>> >>> I guess I should have asked this during this morning's doc session >>> at >>> the summit, but I hadn't had real coffee yet (only decaf!). >>> >>> How do we handle backports reviews? Is one +2 enough (that's what >>> Andreas used to do during the post havana backport storm)? Is self >>> approval a valid option? >>> >>> I'd like to hear what you guys think. >> >> IMO: one sanity-check +2 from someone who is not the submitter > > Agreed. > > Also, backports should not be edited, if there are problems noticed, > we > should do a patch for master to fix those and backport that one, Sounds good to me. Thanks for the feedback! I guess that we could add that info to the upcoming review guide :) Gauvain From gauvain.pocentek at objectif-libre.com Fri May 16 14:23:18 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Fri, 16 May 2014 16:23:18 +0200 Subject: [Openstack-docs] [openstack-dev] [Heat][Documentation] Heat template documentation In-Reply-To: <5374EC0F.7010707@redhat.com> References: <90d4482bcd0b7a52c7262631ffd3baef@objectif-libre.com> <aacbfe99975184407bffdd75638e7171@objectif-libre.com> <5374EC0F.7010707@redhat.com> Message-ID: <508e4c755e0272ea30850b9d333c2d7c@objectif-libre.com> Le 2014-05-15 18:32, Steve Baker a ?crit?: > On 15/05/14 11:54, Gauvain Pocentek wrote: >> (Resending to add openstack-dev) >> >> Gauvain Pocentek >> >> Objectif Libre - Infrastructure et Formations Linux >> http://www.objectif-libre.com >> >> Le 2014-05-15 17:34, Gauvain Pocentek a ?crit : >>> Hello, >>> >>> This mail probably mainly concerns the doc team, but I guess that >>> the >>> heat team wants to know what's going on. >>> >>> We've shortly discussed the state of heat documentation with Anne >>> Gentle and Andreas Jaeger yesterday, and I'd like to share what we >>> think would be nice to do. >>> >>> Currently we only have a small section in the user guide that >>> describes how to start a stack, but nothing documenting how to write >>> templates. The heat developer doc provides a good reference, but I >>> think it's not easy to use to get started. >>> >>> So the idea is to add an "OpenStack Orchestration" chapter in the >>> user guide that would document how to use a cloud with heat, and how >>> to write templates. >>> >>> I've drafted a spec to keep track of this at [0]. >>> >>> Let me know if this sounds OK to you all. >>> >>> Gauvain Pocentek >>> >>> Objectif Libre - Infrastructure et Formations Linux >>> http://www.objectif-libre.com >>> >>> [0]: >>> https://blueprints.launchpad.net/openstack-manuals/+spec/heat-templates >>> > Thanks for raising this, I do hope I can help writing the content. Thanks! > In > addition to this, we will at some point need to port the resource > reference generation to this guide as well. That would be nice. I'm not sure if the user guide is the proper book, but we'll figure out where to put this with the doc team. One thing that would be really useful for users would be to have versioned references. Correct me if I'm wrong, but I think that only the trunk doc is published on the developers doc site. It makes it hard to know which resources are available for a specific version of openstack. Thanks, Gauvain From anne at openstack.org Fri May 16 15:13:48 2014 From: anne at openstack.org (Anne Gentle) Date: Fri, 16 May 2014 10:13:48 -0500 Subject: [Openstack-docs] [Heat][Documentation] Heat template documentation In-Reply-To: <90d4482bcd0b7a52c7262631ffd3baef@objectif-libre.com> References: <90d4482bcd0b7a52c7262631ffd3baef@objectif-libre.com> Message-ID: <CAD0KtVF6qnO4-Kd7ELxJZU53r7jtTSv7mCJG3ZVyJu-C+LxtYA@mail.gmail.com> On Thu, May 15, 2014 at 10:34 AM, Gauvain Pocentek < gauvain.pocentek at objectif-libre.com> wrote: > Hello, > > This mail probably mainly concerns the doc team, but I guess that the heat > team wants to know what's going on. > > We've shortly discussed the state of heat documentation with Anne Gentle > and Andreas Jaeger yesterday, and I'd like to share what we think would be > nice to do. > > Currently we only have a small section in the user guide that describes > how to start a stack, but nothing documenting how to write templates. The > heat developer doc provides a good reference, but I think it's not easy to > use to get started. > > So the idea is to add an "OpenStack Orchestration" chapter in the user > guide that would document how to use a cloud with heat, and how to write > templates. > > I've drafted a spec to keep track of this at [0]. > > I'd like to experiment a bit with converting the End User Guide to an easier markup to enable more contributors to it. Perhaps bringing in Orchestration is a good point to do this, plus it may help address the auto-generation Steve mentions. The loss would be the single sourcing of the End User Guide and Admin User Guide as well as loss of PDF output and loss of translation. If these losses are worthwhile for easier maintenance and to encourage contributions from more cloud consumers, then I'd like to try an experiment with it. The experiment would be to have a new repo set up, openstack/user-guide and use the docs-core team as reviewers on it. Convert the End User Guide from DocBook to RST and build with Sphinx. Use the oslosphinx tempate for output. But what I don't know is if it's possible to build the automated output outside of the openstack/heat repo, does anyone have interest in doing a proof of concept on this? I'd also like input on the loss of features I'm describing above. Is this worth experimenting with? Thanks, Anne > Let me know if this sounds OK to you all. > > Gauvain Pocentek > > Objectif Libre - Infrastructure et Formations Linux > http://www.objectif-libre.com > > [0]: https://blueprints.launchpad.net/openstack-manuals/+spec/ > heat-templates > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140516/db24f774/attachment.html> From anne at openstack.org Fri May 16 15:20:01 2014 From: anne at openstack.org (Anne Gentle) Date: Fri, 16 May 2014 10:20:01 -0500 Subject: [Openstack-docs] Security Guide moving and interested reviewers Message-ID: <CAD0KtVHdUo0DGATzQRqd2gjZPDCtpWBiJQGC+UPTQtB4s6hwvA@mail.gmail.com> Hi all, Bryan Payne and Andreas and I met this week about updates for the Security Guide. We want to move the book into its own repo. [1] The move helps with automatically incorporating the OpenStack Security Notes into an appendix with the Security Guide itself. If you're interested in being a core reviewer on the Security Guide, please let me and Bryan Payne know. Your responsibilities would be to review changes to the Security Guide and OpenStack Security Notes and follow the review guidelines for technical reviews and doc-related reviews. I didn't want to voluntell the entire docs-core team so I'm coming to the list to ask about interest. If there are any ramifications we haven't considered, please let us know! Anne 1. https://review.openstack.org/#/c/93747/ -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140516/70e1c334/attachment.html> From gauvain.pocentek at objectif-libre.com Fri May 16 18:10:35 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Fri, 16 May 2014 20:10:35 +0200 Subject: [Openstack-docs] [Heat][Documentation] Heat template documentation In-Reply-To: <CAD0KtVF6qnO4-Kd7ELxJZU53r7jtTSv7mCJG3ZVyJu-C+LxtYA@mail.gmail.com> References: <90d4482bcd0b7a52c7262631ffd3baef@objectif-libre.com> <CAD0KtVF6qnO4-Kd7ELxJZU53r7jtTSv7mCJG3ZVyJu-C+LxtYA@mail.gmail.com> Message-ID: <37903930f5456fa6f09066fe41cce960@objectif-libre.com> Le 2014-05-16 17:13, Anne Gentle a ?crit?: > On Thu, May 15, 2014 at 10:34 AM, Gauvain Pocentek > <gauvain.pocentek at objectif-libre.com> wrote: > >> Hello, >> >> This mail probably mainly concerns the doc team, but I guess that the >> heat team wants to know what's going on. >> >> We've shortly discussed the state of heat documentation with Anne >> Gentle and Andreas Jaeger yesterday, and I'd like to share what we >> think would be nice to do. >> >> Currently we only have a small section in the user guide that >> describes how to start a stack, but nothing documenting how to write >> templates. The heat developer doc provides a good reference, but I >> think it's not easy to use to get started. >> >> So the idea is to add an "OpenStack Orchestration" chapter in the >> user guide that would document how to use a cloud with heat, and how >> to write templates. >> >> I've drafted a spec to keep track of this at [0]. > > I'd like to experiment a bit with converting the End User Guide to an > easier markup to enable more contributors to it. Perhaps bringing in > Orchestration is a good point to do this, plus it may help address the > auto-generation Steve mentions.? > > The loss would be the single sourcing of the End User Guide and Admin > User Guide as well as loss of PDF output and loss of translation. If > these losses are worthwhile for easier maintenance and to encourage > contributions from more cloud consumers, then I'd like to try an > experiment with it. Using RST would probably make it easier to import/include the developers' documentation. But I'm not sure we can afford to loose the features you mention. Translations for the user guides are very important I think. How would we review changes made in "external" repositories? The user guides are continuously published, this means that a change done in the heat/docs/ dir would quite quickly land on the webserver without a doc team review. I completely trust the developers, but I'm not sure that this is the way to go. > > The experiment would be to have a new repo set up, > openstack/user-guide and use the docs-core team as reviewers on it. > Convert the End User Guide from DocBook to RST and build with Sphinx. > Use the oslosphinx tempate for output. But what I don't know is if > it's possible to build the automated output outside of the > openstack/heat repo, does anyone have interest in doing a proof of > concept on this?? I'm not sure that this is possible, but I'm no RST expert. > I'd also like input on the loss of features I'm describing above. Is > this worth experimenting with? Starting this new book sounds like a lot of work. Right now I'm not convinced it's worth it. Gauvain From anne at openstack.org Sat May 17 03:03:38 2014 From: anne at openstack.org (Anne Gentle) Date: Fri, 16 May 2014 22:03:38 -0500 Subject: [Openstack-docs] Searching for docs reviews in Gerrit Message-ID: <CAD0KtVEzm1_mLY6xGU+Q+8AciKfDS7t5SVEksmk2qFrKd_VAow@mail.gmail.com> A great question came out of a docs session today and I wanted to post this hint/tip here, and also ask a question. Gerrit has documentation that describes how to use regular expressions to search for specific reviews. See https://review.openstack.org/Documentation/user-search.html One that I've found handy for docs reviews is: file:^*REGEX* Matches any change where REGEX matches a file that was affected by the change. The regular expression pattern must start with ^. For example, to match all XML files usefile:^.*\.xml$. The dk.brics.automaton library<http://www.brics.dk/automaton/> is used for the evaluation of such patterns. The ^ required at the beginning of the regular expression not only denotes a regular expression, but it also has the usual meaning of anchoring the match to the start of the string. To match all Java files, use file:^.*\.java. The entire regular expression pattern, including the ^ character, should be double quoted when using more complex construction (like ones using a bracket expression). For example, to match all XML files named like *name1.xml*, *name2.xml*, and *name3.xml* use file:"^name[1-3].xml". For example, if you want to review all RST files that are edited in a repo, log into review.openstack.org, then go to Settings > Watched Projects. Then, on a particular project's repo, look for file:^.*\.rst. One example I'd like to know about -- is it possible to watch all changes to the Networking chapter in the Cloud Admin Guide in the openstack/openstack-manuals repo? This particular search didn't work for me: file:"section_networking-adv-config.xml" project:openstack/openstack-manuals nor does: file:"docs/admin-guide-cloud/networking/section_networking-adv-config.xml" project:openstack/openstack-manuals Any more ideas for focusing on doc reviews in specialty areas? Thanks, Anne -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140516/dd6c4e9d/attachment-0001.html> From aj at suse.com Sat May 17 03:27:27 2014 From: aj at suse.com (Andreas Jaeger) Date: Sat, 17 May 2014 05:27:27 +0200 Subject: [Openstack-docs] Policy for approving backports In-Reply-To: <fec80c3953ae843bbee513bd22d8a1c8@objectif-libre.com> References: <e8ae767f5c80279bb44a1507828e3116@objectif-libre.com> <5374E1B5.1090004@openstack.org> <5374E67C.40504@suse.com> <fec80c3953ae843bbee513bd22d8a1c8@objectif-libre.com> Message-ID: <5376D71F.6080806@suse.com> On 05/16/2014 04:05 PM, Gauvain Pocentek wrote: > Le 2014-05-15 18:08, Andreas Jaeger a ?crit : >> On 05/15/2014 11:48 AM, Tom Fifield wrote: >>> On 15/05/14 11:40, Gauvain Pocentek wrote: >>>> Hello, >>>> >>>> I guess I should have asked this during this morning's doc session at >>>> the summit, but I hadn't had real coffee yet (only decaf!). >>>> >>>> How do we handle backports reviews? Is one +2 enough (that's what >>>> Andreas used to do during the post havana backport storm)? Is self >>>> approval a valid option? >>>> >>>> I'd like to hear what you guys think. >>> >>> IMO: one sanity-check +2 from someone who is not the submitter >> >> Agreed. >> >> Also, backports should not be edited, if there are problems noticed, we >> should do a patch for master to fix those and backport that one, > > Sounds good to me. Thanks for the feedback! > > I guess that we could add that info to the upcoming review guide :) Sure, go ahead ;) But first let Anne approve the blueprint and get the first patch in that creates it ;) Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Sat May 17 16:55:07 2014 From: anne at openstack.org (Anne Gentle) Date: Sat, 17 May 2014 11:55:07 -0500 Subject: [Openstack-docs] Policy for approving backports In-Reply-To: <5374E67C.40504@suse.com> References: <e8ae767f5c80279bb44a1507828e3116@objectif-libre.com> <5374E1B5.1090004@openstack.org> <5374E67C.40504@suse.com> Message-ID: <CAD0KtVEhu6fJhdB07hDTanNfD+kVgGxTb-7S-HFoqWOuNoq0dw@mail.gmail.com> On Thu, May 15, 2014 at 11:08 AM, Andreas Jaeger <aj at suse.com> wrote: > On 05/15/2014 11:48 AM, Tom Fifield wrote: > > On 15/05/14 11:40, Gauvain Pocentek wrote: > >> Hello, > >> > >> I guess I should have asked this during this morning's doc session at > >> the summit, but I hadn't had real coffee yet (only decaf!). > >> > >> How do we handle backports reviews? Is one +2 enough (that's what > >> Andreas used to do during the post havana backport storm)? Is self > >> approval a valid option? > >> > >> I'd like to hear what you guys think. > > > > IMO: one sanity-check +2 from someone who is not the submitter > > Yep, agree with this as well (and I know I need it!) Where's the blueprint? I'm fine with just documenting this standard in the review guide. Anne > Agreed. > > Also, backports should not be edited, if there are problems noticed, we > should do a patch for master to fix those and backport that one, > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140517/c808329f/attachment.html> From annegentle at gmail.com Sat May 17 18:10:21 2014 From: annegentle at gmail.com (annegentle at gmail.com) Date: Sat, 17 May 2014 18:10:21 +0000 Subject: [Openstack-docs] Google Analytics: Pages Message-ID: <089e0111b99a7c5ee204f99c7130@google.com> For your perusal, the Pages report from Google Analytics is attached, showing the Pageviews, Bounce Rate, %Exit and more for pages on the http://docs.openstack.org site. Anne ---------------------------------------- This is a report email from Google Analytics. You received this email because annegentle at gmail.com requested this report be sent to you. If you would like to opt out of emails from this user, go to https://www.google.com/analytics/web/optout?token=52rfpUYBAAA.PXlfi93zuPDcITpdeJeHPjn5Jt8i6hAKPw6q4lsZdoKd9lHq5BdZkEkA1djaWc-TU_un2AulG82SCEmJ7v5Dol5Id1PGOwOxv8TFlzhhjPQ.L3lSrep-0fqxiQ_TAuFaFg&email=openstack-docs%40lists.openstack.org&hl=en_US -------------- next part -------------- A non-text attachment was scrubbed... Name: Analytics Docs Pages 20140417-20140516.pdf Type: application/pdf Size: 108704 bytes Desc: not available URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140517/2f533ba3/attachment-0001.pdf> From mkassawara at gmail.com Sun May 18 01:32:24 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Sat, 17 May 2014 19:32:24 -0600 Subject: [Openstack-docs] Improvements to the Installation Guide Message-ID: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> I created a blueprint for improvements to the Installation Guide. https://blueprints.launchpad.net/openstack-manuals/+spec/installation-guide-improvements The suggested changes currently live in an Etherpad. https://etherpad.openstack.org/p/installation-guide-audit The blueprint needs a specification. Shall I organize our ideas from the Etherpad and add them to a Wiki page with suggested priorities? I'm also curious how we plan to track and divide up the work. I'm thinking about using bugs... either a single one similar to how we handled the Installation Guide networking improvements, or one per chapter, or... other suggestions? -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140517/c29dd16e/attachment.html> From mkassawara at gmail.com Sun May 18 03:22:15 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Sat, 17 May 2014 21:22:15 -0600 Subject: [Openstack-docs] Documentation Guide Message-ID: <CABA+jQos25_TaHw4PVpQJOd7KWbvrr46ypRHQO44AxrkoG3EFg@mail.gmail.com> Similar to the Installation Guide improvements, how shall we handle the Documentation Guide? https://blueprints.launchpad.net/openstack-manuals/+spec/docs-guide -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140517/21c03ed2/attachment.html> From anne at openstack.org Sun May 18 03:46:11 2014 From: anne at openstack.org (Anne Gentle) Date: Sat, 17 May 2014 22:46:11 -0500 Subject: [Openstack-docs] Improvements to the Installation Guide In-Reply-To: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> References: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> Message-ID: <CAD0KtVFTcL-wREXNScM6haHheEKUJHADh_FLPxi0afYzf6mUAA@mail.gmail.com> On Sat, May 17, 2014 at 8:32 PM, Matt Kassawara <mkassawara at gmail.com>wrote: > I created a blueprint for improvements to the Installation Guide. > > > https://blueprints.launchpad.net/openstack-manuals/+spec/installation-guide-improvements > > The suggested changes currently live in an Etherpad. > > https://etherpad.openstack.org/p/installation-guide-audit > > The blueprint needs a specification. Shall I organize our ideas from the > Etherpad and add them to a Wiki page with suggested priorities? > Yep, that's how it works -- see the link "Set the URL for this specification" on that page, we set that to be a wiki page. A good example is https://wiki.openstack.org/wiki/Blueprint-restructure-documentation > I'm also curious how we plan to track and divide up the work. I'm thinking > about using bugs... either a single one similar to how we handled the > Installation Guide networking improvements, or one per chapter, or... other > suggestions? > The blueprint and a detailed wiki page should be enough to track the work rather than individual bugs. Blueprints are typically assigned to a single person, but that person can track for a team. I'd rather the blueprint in this case incorporate all the "bugs" the audit found. Thanks for organizing! Anne > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140517/f5ca2126/attachment.html> From anne at openstack.org Sun May 18 03:48:41 2014 From: anne at openstack.org (Anne Gentle) Date: Sat, 17 May 2014 22:48:41 -0500 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <CABA+jQos25_TaHw4PVpQJOd7KWbvrr46ypRHQO44AxrkoG3EFg@mail.gmail.com> References: <CABA+jQos25_TaHw4PVpQJOd7KWbvrr46ypRHQO44AxrkoG3EFg@mail.gmail.com> Message-ID: <CAD0KtVEkWzdUjmGuaXL+shTb7n9u4hgoEWV_pv5pPpZjrxot9g@mail.gmail.com> On Sat, May 17, 2014 at 10:22 PM, Matt Kassawara <mkassawara at gmail.com>wrote: > Similar to the Installation Guide improvements, how shall we handle the > Documentation Guide? > > https://blueprints.launchpad.net/openstack-manuals/+spec/docs-guide > > In this case, Diane has a start for a docs guide that we may be able to reuse. I'll approve once she has a chance to take a look and see what's re-usable. I'd like a wiki page linked with "Set the URL for this specification" prior to approving this blueprint that contains this analysis. Thanks, Anne > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140517/91e0a471/attachment.html> From berendt at b1-systems.de Sun May 18 09:51:03 2014 From: berendt at b1-systems.de (Christian Berendt) Date: Sun, 18 May 2014 11:51:03 +0200 Subject: [Openstack-docs] Improvements to the Installation Guide In-Reply-To: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> References: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> Message-ID: <53788287.4020203@b1-systems.de> On 05/18/2014 03:32 AM, Matt Kassawara wrote: > The suggested changes currently live in an Etherpad. > > https://etherpad.openstack.org/p/installation-guide-audit Will there be bugs opened first for all the changes mentioned in the Etherpad? I would like to take over some changes but I'm not sure who is responsible for the several changes at the moment and if there is somebody already assigned. Christian. -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 From mkassawara at gmail.com Sun May 18 13:00:08 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Sun, 18 May 2014 07:00:08 -0600 Subject: [Openstack-docs] Improvements to the Installation Guide In-Reply-To: <53788287.4020203@b1-systems.de> References: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> <53788287.4020203@b1-systems.de> Message-ID: <CABA+jQo1HwmujP_BL4W7AkdUs=5Zr6xDSUGD_z477UXqrxXdWw@mail.gmail.com> I suppose we can use the "work items" section in the blueprint or note activities on the Wiki page. On Sun, May 18, 2014 at 3:51 AM, Christian Berendt <berendt at b1-systems.de>wrote: > On 05/18/2014 03:32 AM, Matt Kassawara wrote: > > The suggested changes currently live in an Etherpad. > > > > https://etherpad.openstack.org/p/installation-guide-audit > > Will there be bugs opened first for all the changes mentioned in the > Etherpad? I would like to take over some changes but I'm not sure who is > responsible for the several changes at the moment and if there is > somebody already assigned. > > Christian. > > -- > Christian Berendt > Cloud Computing Solution Architect > Mail: berendt at b1-systems.de > > B1 Systems GmbH > Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de > GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140518/eac10bff/attachment.html> From diane.fleming at RACKSPACE.COM Sun May 18 14:59:26 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Sun, 18 May 2014 14:59:26 +0000 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <CAD0KtVEkWzdUjmGuaXL+shTb7n9u4hgoEWV_pv5pPpZjrxot9g@mail.gmail.com> Message-ID: <CF9E329D.2D4C0%diane.fleming@rackspace.com> Hey Anne, The existing Writers Guide is broken at the moment (meaning, it's not publishing correctly to http://docs.rackspace.com/writers-guide/content/<http://docs.rackspace.com/writers-guide/content/ch_wadl.html> - David C is looking into that. However, I'm thinking that I should convert this to a CONTRIBUTING.rst document in the openstack/openstack-manuals repo, similar to what devs do. Long wikis aren't very useable (IMO). People tend to look for this information in github now. I could also write an API-specific CONTRIBUTING.rst in the openstack/api-site repo. Also, the Rackspace writers have asked me to do something similar for the Rackspace version of this guide. Anne, you can see a copy of the guide here (it's Rackspace internal so others probably can't see it, sorry) http://docs-internal.rackspace.com/process/api/v1/writers-guide/content/ch_preface.html Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com From: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>> Date: Saturday, May 17, 2014 10:48 PM To: Matt Kassawara <mkassawara at gmail.com<mailto:mkassawara at gmail.com>> Cc: "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>> Subject: Re: [Openstack-docs] Documentation Guide On Sat, May 17, 2014 at 10:22 PM, Matt Kassawara <mkassawara at gmail.com<mailto:mkassawara at gmail.com>> wrote: Similar to the Installation Guide improvements, how shall we handle the Documentation Guide? https://blueprints.launchpad.net/openstack-manuals/+spec/docs-guide In this case, Diane has a start for a docs guide that we may be able to reuse. I'll approve once she has a chance to take a look and see what's re-usable. I'd like a wiki page linked with "Set the URL for this specification" prior to approving this blueprint that contains this analysis. Thanks, Anne _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140518/158d79e9/attachment.html> From diane.fleming at RACKSPACE.COM Sun May 18 15:16:12 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Sun, 18 May 2014 15:16:12 +0000 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <CF9E329D.2D4C0%diane.fleming@rackspace.com> Message-ID: <CF9E3883.2D4DA%diane.fleming@rackspace.com> The current Docs guide (Writers Guide) is now up http://docs.rackspace.com/writers-guide/content/ch_preface.html Depending on what the consensus is, I can either move the source files to the repo created by Andreas, or convert to CONTRIBUTING.rst files ? one for openstack-manuals and one for api-site. (I prefer the latter solution). Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com From: Diane Fleming <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>> Date: Sunday, May 18, 2014 9:59 AM To: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>>, Matt Kassawara <mkassawara at gmail.com<mailto:mkassawara at gmail.com>> Cc: "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>> Subject: Re: [Openstack-docs] Documentation Guide Hey Anne, The existing Writers Guide is broken at the moment (meaning, it's not publishing correctly to http://docs.rackspace.com/writers-guide/content/<http://docs.rackspace.com/writers-guide/content/ch_wadl.html> - David C is looking into that. However, I'm thinking that I should convert this to a CONTRIBUTING.rst document in the openstack/openstack-manuals repo, similar to what devs do. Long wikis aren't very useable (IMO). People tend to look for this information in github now. I could also write an API-specific CONTRIBUTING.rst in the openstack/api-site repo. Also, the Rackspace writers have asked me to do something similar for the Rackspace version of this guide. Anne, you can see a copy of the guide here (it's Rackspace internal so others probably can't see it, sorry) http://docs-internal.rackspace.com/process/api/v1/writers-guide/content/ch_preface.html Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com> Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com<mailto:diane.fleming at gmail.com> From: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>> Date: Saturday, May 17, 2014 10:48 PM To: Matt Kassawara <mkassawara at gmail.com<mailto:mkassawara at gmail.com>> Cc: "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>> Subject: Re: [Openstack-docs] Documentation Guide On Sat, May 17, 2014 at 10:22 PM, Matt Kassawara <mkassawara at gmail.com<mailto:mkassawara at gmail.com>> wrote: Similar to the Installation Guide improvements, how shall we handle the Documentation Guide? https://blueprints.launchpad.net/openstack-manuals/+spec/docs-guide In this case, Diane has a start for a docs guide that we may be able to reuse. I'll approve once she has a chance to take a look and see what's re-usable. I'd like a wiki page linked with "Set the URL for this specification" prior to approving this blueprint that contains this analysis. Thanks, Anne _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140518/7f6bfabe/attachment-0001.html> From aj at suse.com Sun May 18 17:56:33 2014 From: aj at suse.com (Andreas Jaeger) Date: Sun, 18 May 2014 19:56:33 +0200 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <CF9E3883.2D4DA%diane.fleming@rackspace.com> References: <CF9E3883.2D4DA%diane.fleming@rackspace.com> Message-ID: <5378F451.9070607@suse.com> On 05/18/2014 05:16 PM, Diane Fleming wrote: > The current Docs guide (Writers Guide) is now up > > http://docs.rackspace.com/writers-guide/content/ch_preface.html Not reachable for me. > Depending on what the consensus is, I can either move the source files > to the repo created by Andreas, or convert to CONTRIBUTING.rst files ? > one for openstack-manuals and one for api-site. > > (I prefer the latter solution). The idea we had at the summit was to move over from the wiki the Conventions and processes - so to have a single place as reference for all contributors, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From diane.fleming at RACKSPACE.COM Sun May 18 19:57:43 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Sun, 18 May 2014 19:57:43 +0000 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <5378F451.9070607@suse.com> References: <CF9E3883.2D4DA%diane.fleming@rackspace.com>, <5378F451.9070607@suse.com> Message-ID: <2D4B651C-AC9E-4744-8B8B-7EB558C7505B@RACKSPACE.COM> Andreas, that link should be reachable for you. Yes, good idea to move conventions to one place. I am fine if it is docbook but would prefer Github repo as i said. Sent from my iPhone > On May 18, 2014, at 12:56 PM, "Andreas Jaeger" <aj at suse.com> wrote: > >> On 05/18/2014 05:16 PM, Diane Fleming wrote: >> The current Docs guide (Writers Guide) is now up >> >> http://docs.rackspace.com/writers-guide/content/ch_preface.html > > Not reachable for me. > >> Depending on what the consensus is, I can either move the source files >> to the repo created by Andreas, or convert to CONTRIBUTING.rst files ? >> one for openstack-manuals and one for api-site. >> >> (I prefer the latter solution). > > The idea we had at the summit was to move over from the wiki the > Conventions and processes - so to have a single place as reference for > all contributors, > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Sun May 18 21:15:51 2014 From: anne at openstack.org (Anne Gentle) Date: Sun, 18 May 2014 16:15:51 -0500 Subject: [Openstack-docs] Improvements to the Installation Guide In-Reply-To: <CABA+jQo1HwmujP_BL4W7AkdUs=5Zr6xDSUGD_z477UXqrxXdWw@mail.gmail.com> References: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> <53788287.4020203@b1-systems.de> <CABA+jQo1HwmujP_BL4W7AkdUs=5Zr6xDSUGD_z477UXqrxXdWw@mail.gmail.com> Message-ID: <CAD0KtVE+BEpom3DSwE_h-0XtCq3UwgUhbE8bgo9y731g0mQL_Q@mail.gmail.com> On Sun, May 18, 2014 at 8:00 AM, Matt Kassawara <mkassawara at gmail.com>wrote: > I suppose we can use the "work items" section in the blueprint or note > activities on the Wiki page. > If you're all willing to work this way, I think it helps us know the "quality" of our docs set by tracking bugs as defect or inaccuracy rather than reorg or gap-filling. What do you think? Is it work-able to track on the wiki page? Let's also talk about how we can make a roadmap-per-book workable while still not causing duplication of effort. My original thinking is that you'd update the roadmap with your patch, but now I realize 2 people could work on a roadmap item at once without knowing the other is doing the same thing. Thoughts? Thanks, Anne > > On Sun, May 18, 2014 at 3:51 AM, Christian Berendt <berendt at b1-systems.de>wrote: > >> On 05/18/2014 03:32 AM, Matt Kassawara wrote: >> > The suggested changes currently live in an Etherpad. >> > >> > https://etherpad.openstack.org/p/installation-guide-audit >> >> Will there be bugs opened first for all the changes mentioned in the >> Etherpad? I would like to take over some changes but I'm not sure who is >> responsible for the several changes at the moment and if there is >> somebody already assigned. >> >> Christian. >> >> -- >> Christian Berendt >> Cloud Computing Solution Architect >> Mail: berendt at b1-systems.de >> >> B1 Systems GmbH >> Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de >> GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140518/55e7850d/attachment.html> From anne at openstack.org Sun May 18 21:16:57 2014 From: anne at openstack.org (Anne Gentle) Date: Sun, 18 May 2014 16:16:57 -0500 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <2D4B651C-AC9E-4744-8B8B-7EB558C7505B@RACKSPACE.COM> References: <CF9E3883.2D4DA%diane.fleming@rackspace.com> <5378F451.9070607@suse.com> <2D4B651C-AC9E-4744-8B8B-7EB558C7505B@RACKSPACE.COM> Message-ID: <CAD0KtVHeqz=uMJpHhAY5XVVmcTm2UYXzE-rDhV97ihN_gXdQ-g@mail.gmail.com> Hey Diane, yep that's the one I was thinking of, but it 404s on the rackspace.com site. Let's make it something that doesn't have to be published but just lives in the repo. Anne On Sun, May 18, 2014 at 2:57 PM, Diane Fleming <diane.fleming at rackspace.com>wrote: > Andreas, that link should be reachable for you. Yes, good idea to move > conventions to one place. I am fine if it is docbook but would prefer > Github repo as i said. > > Sent from my iPhone > > > On May 18, 2014, at 12:56 PM, "Andreas Jaeger" <aj at suse.com> wrote: > > > >> On 05/18/2014 05:16 PM, Diane Fleming wrote: > >> The current Docs guide (Writers Guide) is now up > >> > >> http://docs.rackspace.com/writers-guide/content/ch_preface.html > > > > Not reachable for me. > > > >> Depending on what the consensus is, I can either move the source files > >> to the repo created by Andreas, or convert to CONTRIBUTING.rst files ? > >> one for openstack-manuals and one for api-site. > >> > >> (I prefer the latter solution). > > > > The idea we had at the summit was to move over from the wiki the > > Conventions and processes - so to have a single place as reference for > > all contributors, > > > > Andreas > > -- > > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140518/d76a047f/attachment.html> From mkassawara at gmail.com Sun May 18 23:02:04 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Sun, 18 May 2014 17:02:04 -0600 Subject: [Openstack-docs] Improvements to the Installation Guide In-Reply-To: <CAD0KtVE+BEpom3DSwE_h-0XtCq3UwgUhbE8bgo9y731g0mQL_Q@mail.gmail.com> References: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> <53788287.4020203@b1-systems.de> <CABA+jQo1HwmujP_BL4W7AkdUs=5Zr6xDSUGD_z477UXqrxXdWw@mail.gmail.com> <CAD0KtVE+BEpom3DSwE_h-0XtCq3UwgUhbE8bgo9y731g0mQL_Q@mail.gmail.com> Message-ID: <CABA+jQpeS+Osy3aKdUG=pTuZN6V-v0Wh52GA52AKX=ycVsMnrQ@mail.gmail.com> Any centralized place that we can agree upon to track activity works for me... wiki, etherpad, bug, etc. This also applies to roadmaps. I almost wish we could extend blueprints to handle roadmaps... essentially "living" blueprints that remain open and flexible for the duration of a project. On Sun, May 18, 2014 at 3:15 PM, Anne Gentle <anne at openstack.org> wrote: > > > > On Sun, May 18, 2014 at 8:00 AM, Matt Kassawara <mkassawara at gmail.com>wrote: > >> I suppose we can use the "work items" section in the blueprint or note >> activities on the Wiki page. >> > > If you're all willing to work this way, I think it helps us know the > "quality" of our docs set by tracking bugs as defect or inaccuracy rather > than reorg or gap-filling. What do you think? Is it work-able to track on > the wiki page? > > Let's also talk about how we can make a roadmap-per-book workable while > still not causing duplication of effort. My original thinking is that you'd > update the roadmap with your patch, but now I realize 2 people could work > on a roadmap item at once without knowing the other is doing the same > thing. Thoughts? > Thanks, > Anne > > >> >> On Sun, May 18, 2014 at 3:51 AM, Christian Berendt <berendt at b1-systems.de >> > wrote: >> >>> On 05/18/2014 03:32 AM, Matt Kassawara wrote: >>> > The suggested changes currently live in an Etherpad. >>> > >>> > https://etherpad.openstack.org/p/installation-guide-audit >>> >>> Will there be bugs opened first for all the changes mentioned in the >>> Etherpad? I would like to take over some changes but I'm not sure who is >>> responsible for the several changes at the moment and if there is >>> somebody already assigned. >>> >>> Christian. >>> >>> -- >>> Christian Berendt >>> Cloud Computing Solution Architect >>> Mail: berendt at b1-systems.de >>> >>> B1 Systems GmbH >>> Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de >>> GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 >>> >>> _______________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.openstack.org >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>> >> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140518/a338c999/attachment-0001.html> From yorik.sar at gmail.com Mon May 19 04:31:32 2014 From: yorik.sar at gmail.com (Yuriy Taraday) Date: Mon, 19 May 2014 08:31:32 +0400 Subject: [Openstack-docs] [openstack-dev] Searching for docs reviews in Gerrit In-Reply-To: <CAD0KtVEzm1_mLY6xGU+Q+8AciKfDS7t5SVEksmk2qFrKd_VAow@mail.gmail.com> References: <CAD0KtVEzm1_mLY6xGU+Q+8AciKfDS7t5SVEksmk2qFrKd_VAow@mail.gmail.com> Message-ID: <CABocrW4nhsP9MKiBhUS_Nyf7AsHWr2ZoV=ysmBbZWTU+ceUUYw@mail.gmail.com> Hello, Anne. On Sat, May 17, 2014 at 7:03 AM, Anne Gentle <anne at openstack.org> wrote: > file:"section_networking-adv-config.xml" > project:openstack/openstack-manuals > As it's stated in the manual: "The regular expression pattern must start with ^." Meaning that it'll always look only for files whose paths start with string matching this regex not just include them. > nor does: > file:"docs/admin-guide-cloud/networking/section_networking-adv-config.xml" > project:openstack/openstack-manuals > You've misspelled the first dir name - it's "doc" and it's working. -- Kind regards, Yuriy. -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140519/bf2deaf7/attachment.html> From aj at suse.com Mon May 19 08:26:28 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 19 May 2014 10:26:28 +0200 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <2D4B651C-AC9E-4744-8B8B-7EB558C7505B@RACKSPACE.COM> References: <CF9E3883.2D4DA%diane.fleming@rackspace.com>, <5378F451.9070607@suse.com> <2D4B651C-AC9E-4744-8B8B-7EB558C7505B@RACKSPACE.COM> Message-ID: <5379C034.5040808@suse.com> On 05/18/2014 09:57 PM, Diane Fleming wrote: > Andreas, that link should be reachable for you. Yes, good idea to move conventions to one place. I am fine if it is docbook but would prefer Github repo as i said. The link does not work. So, you want to have it in a *separate* repo? Matt and myself wanted to have it as part of openstack-manuals - just as a separate guide/directory. Andreas > Sent from my iPhone > >> On May 18, 2014, at 12:56 PM, "Andreas Jaeger" <aj at suse.com> wrote: >> >>> On 05/18/2014 05:16 PM, Diane Fleming wrote: >>> The current Docs guide (Writers Guide) is now up >>> >>> http://docs.rackspace.com/writers-guide/content/ch_preface.html >> >> Not reachable for me. >> >>> Depending on what the consensus is, I can either move the source files >>> to the repo created by Andreas, or convert to CONTRIBUTING.rst files ? >>> one for openstack-manuals and one for api-site. >>> >>> (I prefer the latter solution). >> >> The idea we had at the summit was to move over from the wiki the >> Conventions and processes - so to have a single place as reference for >> all contributors, >> >> Andreas >> -- >> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany >> GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Mon May 19 08:27:08 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 19 May 2014 10:27:08 +0200 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <CAD0KtVHeqz=uMJpHhAY5XVVmcTm2UYXzE-rDhV97ihN_gXdQ-g@mail.gmail.com> References: <CF9E3883.2D4DA%diane.fleming@rackspace.com> <5378F451.9070607@suse.com> <2D4B651C-AC9E-4744-8B8B-7EB558C7505B@RACKSPACE.COM> <CAD0KtVHeqz=uMJpHhAY5XVVmcTm2UYXzE-rDhV97ihN_gXdQ-g@mail.gmail.com> Message-ID: <5379C05C.4020304@suse.com> On 05/18/2014 11:16 PM, Anne Gentle wrote: > Hey Diane, yep that's the one I was thinking of, but it 404s on the > rackspace.com <http://rackspace.com> site. > > Let's make it something that doesn't have to be published but just lives > in the repo. Anne, if we move conventions and process in it, we should publish the content, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From diane.fleming at RACKSPACE.COM Mon May 19 11:39:07 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Mon, 19 May 2014 11:39:07 +0000 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <5379C05C.4020304@suse.com> References: <CF9E3883.2D4DA%diane.fleming@rackspace.com> <5378F451.9070607@suse.com> <2D4B651C-AC9E-4744-8B8B-7EB558C7505B@RACKSPACE.COM> <CAD0KtVHeqz=uMJpHhAY5XVVmcTm2UYXzE-rDhV97ihN_gXdQ-g@mail.gmail.com>, <5379C05C.4020304@suse.com> Message-ID: <B92BB4DE-C27F-4D6D-9287-A4E4C6A5C408@RACKSPACE.COM> Why do we need to publish it if we move it to something like CONTRIBUTING.rst, which would be viewable if you open the file while in the repo? That's how dev does it. Sent from my iPhone > On May 19, 2014, at 3:27 AM, "Andreas Jaeger" <aj at suse.com> wrote: > >> On 05/18/2014 11:16 PM, Anne Gentle wrote: >> Hey Diane, yep that's the one I was thinking of, but it 404s on the >> rackspace.com <http://rackspace.com> site. >> >> Let's make it something that doesn't have to be published but just lives >> in the repo. > > Anne, if we move conventions and process in it, we should publish the > content, > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Mon May 19 11:55:46 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 19 May 2014 13:55:46 +0200 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <B92BB4DE-C27F-4D6D-9287-A4E4C6A5C408@RACKSPACE.COM> References: <CF9E3883.2D4DA%diane.fleming@rackspace.com> <5378F451.9070607@suse.com> <2D4B651C-AC9E-4744-8B8B-7EB558C7505B@RACKSPACE.COM> <CAD0KtVHeqz=uMJpHhAY5XVVmcTm2UYXzE-rDhV97ihN_gXdQ-g@mail.gmail.com>, <5379C05C.4020304@suse.com> <B92BB4DE-C27F-4D6D-9287-A4E4C6A5C408@RACKSPACE.COM> Message-ID: <5379F142.3020808@suse.com> On 05/19/2014 01:39 PM, Diane Fleming wrote: > Why do we need to publish it if we move it to something like CONTRIBUTING.rst, which would be viewable if you open the file while in the repo? That's how dev does it. The idea was to have a document that includes Conventions, processes - and we want to be able to give a URL during review to point out a issue. Best would be a quasi permanent URL and not a link to some line in a document that changes... Andreas > Sent from my iPhone > >> On May 19, 2014, at 3:27 AM, "Andreas Jaeger" <aj at suse.com> wrote: >> >>> On 05/18/2014 11:16 PM, Anne Gentle wrote: >>> Hey Diane, yep that's the one I was thinking of, but it 404s on the >>> rackspace.com <http://rackspace.com> site. >>> >>> Let's make it something that doesn't have to be published but just lives >>> in the repo. >> >> Anne, if we move conventions and process in it, we should publish the >> content, >> >> Andreas >> -- >> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany >> GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Mon May 19 17:17:27 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 19 May 2014 19:17:27 +0200 Subject: [Openstack-docs] Translation gate for doc jobs In-Reply-To: <5375FE39.20904@openstack.org> References: <5375284F.3030208@suse.com> <5375FE39.20904@openstack.org> Message-ID: <537A3CA7.8080100@suse.com> On 05/16/2014 02:02 PM, Tom Fifield wrote: > On 15/05/14 16:49, Andreas Jaeger wrote: >> Inspired by some discussions here at the summit, I'd like to setup some >> translation gate for jobs. >> >> Patch https://review.openstack.org/93526 (merged) sets up a test that >> can be invoked with "tox -e checklang" which builds all "supported" manuals. >> >> I propose the following: >> >> * Setup checking/gating jobs that runs this test and mark it as non-voting. >> * Create policy on how to handle failures. >> >> Proposed policy: >> * We only gate on manual/language combinations that are translated >> sufficiently. Right now that's for openstack-manuals Japanese with the >> Security Guide, HA Guide and Install Guides only. >> * If an import from transifex fails, creates a failure, we do not >> approve the import. >> * If any other patch fails, the failure might get ignored. >> * In any case of failure, let's send an email to the openstack-i18n >> mailing list asking them to investigate and fix. >> >> What do you think? > > Good, but I'd prefer the creation of a bug in openstack-i18n on > launchpad, instead of a mailing list post. This way people who are > interested in fixing such things can get notified by email (through bug > tracker subscriptions), and the mailing list is kept clear for people > who just want to translate things and participate in the community in > other ways :) fine with me. I'll document this in the wiki once the job is in, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Mon May 19 17:21:21 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 19 May 2014 19:21:21 +0200 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <CAD0KtVEkWzdUjmGuaXL+shTb7n9u4hgoEWV_pv5pPpZjrxot9g@mail.gmail.com> References: <CABA+jQos25_TaHw4PVpQJOd7KWbvrr46ypRHQO44AxrkoG3EFg@mail.gmail.com> <CAD0KtVEkWzdUjmGuaXL+shTb7n9u4hgoEWV_pv5pPpZjrxot9g@mail.gmail.com> Message-ID: <537A3D91.1060006@suse.com> On 05/18/2014 05:48 AM, Anne Gentle wrote: > > > > On Sat, May 17, 2014 at 10:22 PM, Matt Kassawara <mkassawara at gmail.com > <mailto:mkassawara at gmail.com>> wrote: > > Similar to the Installation Guide improvements, how shall we handle > the Documentation Guide? > > https://blueprints.launchpad.net/openstack-manuals/+spec/docs-guide > > > In this case, Diane has a start for a docs guide that we may be able to > reuse. I'll approve once she has a chance to take a look and see what's > re-usable. I'd like a wiki page linked with "Set the URL for this > specification" prior to approving this blueprint that contains this > analysis. Wiki page was created by Matt and has initial content, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Mon May 19 17:27:07 2014 From: anne at openstack.org (Anne Gentle) Date: Mon, 19 May 2014 12:27:07 -0500 Subject: [Openstack-docs] Translation gate for doc jobs In-Reply-To: <5375284F.3030208@suse.com> References: <5375284F.3030208@suse.com> Message-ID: <CAD0KtVFooB-KqsYe82Rm1kQ0qVimv8asDK7Sd3COHUWBzVD6Pg@mail.gmail.com> On Thu, May 15, 2014 at 3:49 PM, Andreas Jaeger <aj at suse.com> wrote: > Inspired by some discussions here at the summit, I'd like to setup some > translation gate for jobs. > > Patch https://review.openstack.org/93526 (merged) sets up a test that > can be invoked with "tox -e checklang" which builds all "supported" > manuals. > > I propose the following: > > * Setup checking/gating jobs that runs this test and mark it as non-voting. > I'm fine with this, the only difficulty is that we need to be sure there are knowledgeable people who can troubleshoot when a job fails. > * Create policy on how to handle failures. > Yep, that's what I need, preferably a contact person. > > Proposed policy: > * We only gate on manual/language combinations that are translated > sufficiently. Right now that's for openstack-manuals Japanese with the > Security Guide, HA Guide and Install Guides only. > Is sufficiently defined as 50% translated or more? Is a single additional language at 50% enough? Just wanting some metric definition. > * If an import from transifex fails, creates a failure, we do not > approve the import. > Agreed. > * If any other patch fails, the failure might get ignored. > * In any case of failure, let's send an email to the openstack-i18n > mailing list asking them to investigate and fix. > Yep, I like the bug idea as well, seems to help with tracking and "is anyone assigned" sorts of questions. Thanks for working through this! Anne > > What do you think? > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140519/dcef8e89/attachment.html> From diane.fleming at RACKSPACE.COM Mon May 19 17:33:04 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Mon, 19 May 2014 17:33:04 +0000 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <537A3D91.1060006@suse.com> Message-ID: <CF9FAA6E.2D63B%diane.fleming@rackspace.com> Is it okay to add to that content on wiki page? Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com On 5/19/14 12:21 PM, "Andreas Jaeger" <aj at suse.com> wrote: >On 05/18/2014 05:48 AM, Anne Gentle wrote: >> >> >> >> On Sat, May 17, 2014 at 10:22 PM, Matt Kassawara <mkassawara at gmail.com >> <mailto:mkassawara at gmail.com>> wrote: >> >> Similar to the Installation Guide improvements, how shall we handle >> the Documentation Guide? >> >> https://blueprints.launchpad.net/openstack-manuals/+spec/docs-guide >> >> >> In this case, Diane has a start for a docs guide that we may be able to >> reuse. I'll approve once she has a chance to take a look and see what's >> re-usable. I'd like a wiki page linked with "Set the URL for this >> specification" prior to approving this blueprint that contains this >> analysis. > >Wiki page was created by Matt and has initial content, > >Andreas >-- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > >_______________________________________________ >Openstack-docs mailing list >Openstack-docs at lists.openstack.org >http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs From aj at suse.com Mon May 19 17:44:26 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 19 May 2014 19:44:26 +0200 Subject: [Openstack-docs] Translation gate for doc jobs In-Reply-To: <CAD0KtVFooB-KqsYe82Rm1kQ0qVimv8asDK7Sd3COHUWBzVD6Pg@mail.gmail.com> References: <5375284F.3030208@suse.com> <CAD0KtVFooB-KqsYe82Rm1kQ0qVimv8asDK7Sd3COHUWBzVD6Pg@mail.gmail.com> Message-ID: <537A42FA.4000302@suse.com> On 05/19/2014 07:27 PM, Anne Gentle wrote: > > > > On Thu, May 15, 2014 at 3:49 PM, Andreas Jaeger <aj at suse.com > <mailto:aj at suse.com>> wrote: > > Inspired by some discussions here at the summit, I'd like to setup some > translation gate for jobs. > > Patch https://review.openstack.org/93526 (merged) sets up a test that > can be invoked with "tox -e checklang" which builds all "supported" > manuals. > > I propose the following: > > * Setup checking/gating jobs that runs this test and mark it as > non-voting. > > > I'm fine with this, the only difficulty is that we need to be sure there > are knowledgeable people who can troubleshoot when a job fails. There are some as noticed with the last failure ;) > > * Create policy on how to handle failures. > > > Yep, that's what I need, preferably a contact person. With a bug report, we abstracted this ;) > > > > Proposed policy: > * We only gate on manual/language combinations that are translated > sufficiently. Right now that's for openstack-manuals Japanese with the > Security Guide, HA Guide and Install Guides only. > > > Is sufficiently defined as 50% translated or more? Is a single > additional language at 50% enough? Just wanting some metric definition. We agreed on only downloading files that are at least translated to 75% - see https://review.openstack.org/92997. So, metric is better than 75 %. > > * If an import from transifex fails, creates a failure, we do not > approve the import. > > > Agreed. > > > * If any other patch fails, the failure might get ignored. > * In any case of failure, let's send an email to the openstack-i18n > mailing list asking them to investigate and fix. > > > Yep, I like the bug idea as well, seems to help with tracking and "is > anyone assigned" sorts of questions. Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From diane.fleming at RACKSPACE.COM Mon May 19 18:19:52 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Mon, 19 May 2014 18:19:52 +0000 Subject: [Openstack-docs] Documentation Guide In-Reply-To: <537A3D91.1060006@suse.com> Message-ID: <CF9FB551.2D664%diane.fleming@rackspace.com> Writer's guide is back up here: http://docs.rackspace.com/writers-guide/content/ch_preface.html Thank you David Cramer! Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com On 5/19/14 12:21 PM, "Andreas Jaeger" <aj at suse.com> wrote: >On 05/18/2014 05:48 AM, Anne Gentle wrote: >> >> >> >> On Sat, May 17, 2014 at 10:22 PM, Matt Kassawara <mkassawara at gmail.com >> <mailto:mkassawara at gmail.com>> wrote: >> >> Similar to the Installation Guide improvements, how shall we handle >> the Documentation Guide? >> >> https://blueprints.launchpad.net/openstack-manuals/+spec/docs-guide >> >> >> In this case, Diane has a start for a docs guide that we may be able to >> reuse. I'll approve once she has a chance to take a look and see what's >> re-usable. I'd like a wiki page linked with "Set the URL for this >> specification" prior to approving this blueprint that contains this >> analysis. > >Wiki page was created by Matt and has initial content, > >Andreas >-- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > >_______________________________________________ >Openstack-docs mailing list >Openstack-docs at lists.openstack.org >http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs From aj at suse.com Mon May 19 20:41:01 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 19 May 2014 22:41:01 +0200 Subject: [Openstack-docs] Target audience Message-ID: <537A6C5D.9090600@suse.com> We had some discussion about target audience for each guide at the OpenStack summit and Anne filed this bug: https://bugs.launchpad.net/openstack-manuals/+bug/1319394 . As a first step, I've went over all guides and categorized them according to target audience and then copied all the current abstracts together. Is the following accurate? Andreas Overview of personas/target audience: Operations Guide Cloud Administrator Guide Configuration Reference HA Guide Install Guide Security Guide Admin User Guide These guides target cloud administrators who sets up an OpenStack cloud and configures the OpenStack services. End User Guide Image Guide These guide targets users using an OpenStack cloud. CLI Reference This guide targets both cloud administrators and users using an OpenStack cloud. Not covered personas: Developer writing applications running in an OpenStack Cloud. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Detailed information - copy of current abstract: Install Guide The OpenStack? system consists of several key projects that you install separately but that work together depending on your cloud needs. These projects include Compute, Identity Service, Networking, Image Service, Block Storage, Object Storage, Telemetry, Orchestration, and Database. You can install any of these projects separately and configure them stand-alone or as connected entities. This guide shows you how to install OpenStack by using packages on openSUSE through the Open Build Service Cloud repository. Explanations of configuration options and sample configuration files are included. Operations Guide This book provides information about designing and operating OpenStack clouds. Cloud Administrator Guide OpenStack offers open source software for cloud administrators to manage and troubleshoot an OpenStack cloud. Configuration Reference This document is for system administrators who want to look up configuration options. It contains lists of configuration options available with OpenStack and uses auto-generation to generate options and the descriptions from the code for each project. It includes sample configuration files. HA Guide No abstract given. Security Guide This book provides best practices and conceptual information about securing an OpenStack cloud. Admin User Guide OpenStack is an open source cloud computing platform for public and private clouds. A series of interrelated projects deliver a cloud infrastructure solution. This guide shows OpenStack admin users how to create and manage resources in an OpenStack cloud with the OpenStack dashboard or OpenStack client commands. End User Guide OpenStack is an open-source cloud computing platform for public and private clouds. A series of interrelated projects deliver a cloud infrastructure solution. This guide shows OpenStack end users how to create and manage resources in an OpenStack cloud with the OpenStack dashboard and OpenStack client commands. Image Guide This guide describes how to obtain, create, and modify virtual machine images that are compatible with OpenStack. CLI Reference This guide documents the OpenStack command-line clients. -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From Randy_Perryman at Dell.com Mon May 19 21:43:20 2014 From: Randy_Perryman at Dell.com (Randy_Perryman at Dell.com) Date: Mon, 19 May 2014 16:43:20 -0500 Subject: [Openstack-docs] Target audience In-Reply-To: <537A6C5D.9090600@suse.com> References: <537A6C5D.9090600@suse.com> Message-ID: <FC6A4A6096337446A48E483EA34F205027142368A6@AUSX7MCPC102.AMER.DELL.COM> Hi, I like your breakdown. I propose a little more granular proposal on the Operations side. Breaking them down to Operations, Installation and Security : Operations Guide Cloud Administrator Guide Admin User Guide This guide is targeted for the day to day operations of an OpenStack cloud system ------------------------ Configuration Reference HA Guide Install Guide These guides target cloud administrators who sets up an OpenStack cloud and configures the OpenStack services. ------------------------ Security Guide This guide is targeted for the Security Administrator of a cloud team and can be referenced to harden existing OpenStack deployments or to evaluate the security controls of OpenStack cloud providers. ------------------------ -Randy P.S. I opened a bug - HA guide does not have an abstract. -----Original Message----- From: Andreas Jaeger [mailto:aj at suse.com] Sent: Monday, May 19, 2014 4:41 PM To: openstack-docs at lists.openstack.org Subject: [Openstack-docs] Target audience We had some discussion about target audience for each guide at the OpenStack summit and Anne filed this bug: https://bugs.launchpad.net/openstack-manuals/+bug/1319394 . As a first step, I've went over all guides and categorized them according to target audience and then copied all the current abstracts together. Is the following accurate? Andreas Overview of personas/target audience: Operations Guide Cloud Administrator Guide Configuration Reference HA Guide Install Guide Security Guide Admin User Guide These guides target cloud administrators who sets up an OpenStack cloud and configures the OpenStack services. End User Guide Image Guide These guide targets users using an OpenStack cloud. CLI Reference This guide targets both cloud administrators and users using an OpenStack cloud. Not covered personas: Developer writing applications running in an OpenStack Cloud. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Detailed information - copy of current abstract: Install Guide The OpenStack? system consists of several key projects that you install separately but that work together depending on your cloud needs. These projects include Compute, Identity Service, Networking, Image Service, Block Storage, Object Storage, Telemetry, Orchestration, and Database. You can install any of these projects separately and configure them stand-alone or as connected entities. This guide shows you how to install OpenStack by using packages on openSUSE through the Open Build Service Cloud repository. Explanations of configuration options and sample configuration files are included. Operations Guide This book provides information about designing and operating OpenStack clouds. Cloud Administrator Guide OpenStack offers open source software for cloud administrators to manage and troubleshoot an OpenStack cloud. Configuration Reference This document is for system administrators who want to look up configuration options. It contains lists of configuration options available with OpenStack and uses auto-generation to generate options and the descriptions from the code for each project. It includes sample configuration files. HA Guide No abstract given. Security Guide This book provides best practices and conceptual information about securing an OpenStack cloud. Admin User Guide OpenStack is an open source cloud computing platform for public and private clouds. A series of interrelated projects deliver a cloud infrastructure solution. This guide shows OpenStack admin users how to create and manage resources in an OpenStack cloud with the OpenStack dashboard or OpenStack client commands. End User Guide OpenStack is an open-source cloud computing platform for public and private clouds. A series of interrelated projects deliver a cloud infrastructure solution. This guide shows OpenStack end users how to create and manage resources in an OpenStack cloud with the OpenStack dashboard and OpenStack client commands. Image Guide This guide describes how to obtain, create, and modify virtual machine images that are compatible with OpenStack. CLI Reference This guide documents the OpenStack command-line clients. -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs From anne at openstack.org Tue May 20 05:18:16 2014 From: anne at openstack.org (Anne Gentle) Date: Tue, 20 May 2014 00:18:16 -0500 Subject: [Openstack-docs] Target audience In-Reply-To: <537A6C5D.9090600@suse.com> References: <537A6C5D.9090600@suse.com> Message-ID: <CAD0KtVHqbi84aHmu+PmmZfYZJmW918ebrHiTogfRvQSq=6e7jg@mail.gmail.com> Thanks for analyzing Andreas and Randy! I like these three simple personas below. Alice the admin Alice is an administrator who is responsible for maintaining (and securing) the OpenStack cloud installation. She has many years of experience with Linux systems administration. Darren the deployer Darren is responsible for doing the initial OpenStack deployment on the host machines. Emile the end-user Emile uses the cloud to do software development inside of the virtual machines. She uses the command-line tools because she finds it quicker than using the dashboard. To me, Emile is a useful persona because she uses user tools and developer tools -- and I do see a lot of blending across user/dev tools. Andreas, the user we haven't yet started to document for is the application devops role, the operator who would monitor applications in the cloud. They might be super specialized for monitoring of the VMs themselves. But I'm not sure whether there's a fourth persona who does planning and setup, what do you all think? Archie the architect? We also don't have to be super pattern-based, we can just write a section describing the audience for each guide. On Mon, May 19, 2014 at 3:41 PM, Andreas Jaeger <aj at suse.com> wrote: > We had some discussion about target audience for each guide at the > OpenStack summit and Anne filed this bug: > https://bugs.launchpad.net/openstack-manuals/+bug/1319394 . As a first > step, I've went over all guides and categorized them according to target > audience and then copied all the current abstracts together. Is the > following accurate? > > Andreas > > Overview of personas/target audience: > > Operations Guide > Cloud Administrator Guide > Configuration Reference > HA Guide > Install Guide > Security Guide > Admin User Guide > > These guides target cloud administrators who sets up an OpenStack > cloud and configures the OpenStack services. > > End User Guide > Image Guide > > These guide targets users using an OpenStack cloud. > > CLI Reference > > This guide targets both cloud administrators and users using an > OpenStack cloud. > > Not covered personas: > > Developer writing applications running in an OpenStack Cloud. > > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > Detailed information - copy of current abstract: > > Install Guide > > The OpenStack? system consists of several key projects that you > install separately but that work together depending on your cloud > needs. These projects include Compute, Identity Service, Networking, > Image Service, Block Storage, Object Storage, Telemetry, > Orchestration, and Database. You can install any of these projects > separately and configure them stand-alone or as connected > entities. This guide shows you how to install OpenStack by using > packages on openSUSE through the Open Build Service Cloud > repository. Explanations of configuration options and sample > configuration files are included. > > > Operations Guide > > This book provides information about designing and operating OpenStack > clouds. > > Cloud Administrator Guide > > OpenStack offers open source software for cloud administrators to > manage and troubleshoot an OpenStack cloud. > > Configuration Reference > > This document is for system administrators who want to look up > configuration options. It contains lists of configuration options > available with OpenStack and uses auto-generation to generate options > and the descriptions from the code for each project. It includes > sample configuration files. > > HA Guide > > No abstract given. > > Security Guide > > This book provides best practices and conceptual information about > securing an OpenStack cloud. > > Admin User Guide > > OpenStack is an open source cloud computing platform for public and > private clouds. A series of interrelated projects deliver a cloud > infrastructure solution. This guide shows OpenStack admin users how to > create and manage resources in an OpenStack cloud with the OpenStack > dashboard or OpenStack client commands. > > > End User Guide > > OpenStack is an open-source cloud computing platform for public and > private clouds. A series of interrelated projects deliver a cloud > infrastructure solution. This guide shows OpenStack end users how to > create and manage resources in an OpenStack cloud with the OpenStack > dashboard and OpenStack client commands. > > Image Guide > > This guide describes how to obtain, create, and modify virtual machine > images that are compatible with OpenStack. > > CLI Reference > > This guide documents the OpenStack command-line clients. > > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140520/ec72eecd/attachment.html> From aj at suse.com Tue May 20 07:36:30 2014 From: aj at suse.com (Andreas Jaeger) Date: Tue, 20 May 2014 09:36:30 +0200 Subject: [Openstack-docs] Target audience In-Reply-To: <CAD0KtVHqbi84aHmu+PmmZfYZJmW918ebrHiTogfRvQSq=6e7jg@mail.gmail.com> References: <537A6C5D.9090600@suse.com> <CAD0KtVHqbi84aHmu+PmmZfYZJmW918ebrHiTogfRvQSq=6e7jg@mail.gmail.com> Message-ID: <537B05FE.8060701@suse.com> On 05/20/2014 07:18 AM, Anne Gentle wrote: > Thanks for analyzing Andreas and Randy! > > I like these three simple personas below. > > Alice the admin > Alice is an administrator who is responsible for maintaining (and > securing) the OpenStack cloud installation. She has many years of > experience with Linux systems administration. > > Darren the deployer > Darren is responsible for doing the initial OpenStack deployment on the > host machines. > Emile the end-user > Emile uses the cloud to do software development inside of the virtual > machines. She uses the command-line tools because she finds it quicker > than using the dashboard. Yes, these are fine - but let's rename Alice since Alice and Bob are the two persons used in the Security Guide explaining the two different setups. > To me, Emile is a useful persona because she uses user tools and > developer tools -- and I do see a lot of blending across user/dev tools. > Andreas, the user we haven't yet started to document for is the > application devops role, the operator who would monitor applications in > the cloud. They might be super specialized for monitoring of the VMs > themselves. > > But I'm not sure whether there's a fourth persona who does planning and > setup, what do you all think? Archie the architect? So, the OPS guide would be for Archie? > We also don't have to be super pattern-based, we can just write a > section describing the audience for each guide. ;) Andreas > > On Mon, May 19, 2014 at 3:41 PM, Andreas Jaeger <aj at suse.com > <mailto:aj at suse.com>> wrote: > > We had some discussion about target audience for each guide at the > OpenStack summit and Anne filed this bug: > https://bugs.launchpad.net/openstack-manuals/+bug/1319394 . As a first > step, I've went over all guides and categorized them according to target > audience and then copied all the current abstracts together. Is the > following accurate? > > Andreas > > Overview of personas/target audience: > > Operations Guide > Cloud Administrator Guide > Configuration Reference > HA Guide > Install Guide > Security Guide > Admin User Guide > > These guides target cloud administrators who sets up an OpenStack > cloud and configures the OpenStack services. > > End User Guide > Image Guide > > These guide targets users using an OpenStack cloud. > > CLI Reference > > This guide targets both cloud administrators and users using an > OpenStack cloud. > > Not covered personas: > > Developer writing applications running in an OpenStack Cloud. > > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > Detailed information - copy of current abstract: > > Install Guide > > The OpenStack? system consists of several key projects that you > install separately but that work together depending on your cloud > needs. These projects include Compute, Identity Service, Networking, > Image Service, Block Storage, Object Storage, Telemetry, > Orchestration, and Database. You can install any of these projects > separately and configure them stand-alone or as connected > entities. This guide shows you how to install OpenStack by using > packages on openSUSE through the Open Build Service Cloud > repository. Explanations of configuration options and sample > configuration files are included. > > > Operations Guide > > This book provides information about designing and operating OpenStack > clouds. > > Cloud Administrator Guide > > OpenStack offers open source software for cloud administrators to > manage and troubleshoot an OpenStack cloud. > > Configuration Reference > > This document is for system administrators who want to look up > configuration options. It contains lists of configuration options > available with OpenStack and uses auto-generation to generate options > and the descriptions from the code for each project. It includes > sample configuration files. > > HA Guide > > No abstract given. > > Security Guide > > This book provides best practices and conceptual information about > securing an OpenStack cloud. > > Admin User Guide > > OpenStack is an open source cloud computing platform for public and > private clouds. A series of interrelated projects deliver a cloud > infrastructure solution. This guide shows OpenStack admin users how to > create and manage resources in an OpenStack cloud with the OpenStack > dashboard or OpenStack client commands. > > > End User Guide > > OpenStack is an open-source cloud computing platform for public and > private clouds. A series of interrelated projects deliver a cloud > infrastructure solution. This guide shows OpenStack end users how to > create and manage resources in an OpenStack cloud with the OpenStack > dashboard and OpenStack client commands. > > Image Guide > > This guide describes how to obtain, create, and modify virtual machine > images that are compatible with OpenStack. > > CLI Reference > > This guide documents the OpenStack command-line clients. > > -- > Andreas Jaeger aj@{suse.com <http://suse.com>,opensuse.org > <http://opensuse.org>} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > <mailto:Openstack-docs at lists.openstack.org> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Tue May 20 12:12:19 2014 From: anne at openstack.org (Anne Gentle) Date: Tue, 20 May 2014 07:12:19 -0500 Subject: [Openstack-docs] Target audience In-Reply-To: <537B05FE.8060701@suse.com> References: <537A6C5D.9090600@suse.com> <CAD0KtVHqbi84aHmu+PmmZfYZJmW918ebrHiTogfRvQSq=6e7jg@mail.gmail.com> <537B05FE.8060701@suse.com> Message-ID: <CAD0KtVHWohWkRbOZag4VWhRmvyHbnxP+d-hVr1q_DGQg=Rc2Mg@mail.gmail.com> Oh we don't have to use those names in the actual metadata in the book. I was just making sure we're using personas recognized in the rest of the community. The audience statement is more like "Who this Book is For" in the Ops Guide: http://docs.openstack.org/trunk/openstack-ops/content/openstack-ops_preface.html#who-this-book-is-for On Tue, May 20, 2014 at 2:36 AM, Andreas Jaeger <aj at suse.com> wrote: > On 05/20/2014 07:18 AM, Anne Gentle wrote: > > Thanks for analyzing Andreas and Randy! > > > > I like these three simple personas below. > > > > Alice the admin > > Alice is an administrator who is responsible for maintaining (and > > securing) the OpenStack cloud installation. She has many years of > > experience with Linux systems administration. > > > > Darren the deployer > > Darren is responsible for doing the initial OpenStack deployment on the > > host machines. > > Emile the end-user > > Emile uses the cloud to do software development inside of the virtual > > machines. She uses the command-line tools because she finds it quicker > > than using the dashboard. > > Yes, these are fine - but let's rename Alice since Alice and Bob are the > two persons used in the Security Guide explaining the two different setups. > > > To me, Emile is a useful persona because she uses user tools and > > developer tools -- and I do see a lot of blending across user/dev tools. > > Andreas, the user we haven't yet started to document for is the > > application devops role, the operator who would monitor applications in > > the cloud. They might be super specialized for monitoring of the VMs > > themselves. > > > > But I'm not sure whether there's a fourth persona who does planning and > > setup, what do you all think? Archie the architect? > > So, the OPS guide would be for Archie? > > > We also don't have to be super pattern-based, we can just write a > > section describing the audience for each guide. > > ;) > > Andreas > > > > > On Mon, May 19, 2014 at 3:41 PM, Andreas Jaeger <aj at suse.com > > <mailto:aj at suse.com>> wrote: > > > > We had some discussion about target audience for each guide at the > > OpenStack summit and Anne filed this bug: > > https://bugs.launchpad.net/openstack-manuals/+bug/1319394 . As a > first > > step, I've went over all guides and categorized them according to > target > > audience and then copied all the current abstracts together. Is the > > following accurate? > > > > Andreas > > > > Overview of personas/target audience: > > > > Operations Guide > > Cloud Administrator Guide > > Configuration Reference > > HA Guide > > Install Guide > > Security Guide > > Admin User Guide > > > > These guides target cloud administrators who sets up an OpenStack > > cloud and configures the OpenStack services. > > > > End User Guide > > Image Guide > > > > These guide targets users using an OpenStack cloud. > > > > CLI Reference > > > > This guide targets both cloud administrators and users using an > > OpenStack cloud. > > > > Not covered personas: > > > > Developer writing applications running in an OpenStack Cloud. > > > > > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > Detailed information - copy of current abstract: > > > > Install Guide > > > > The OpenStack? system consists of several key projects that you > > install separately but that work together depending on your cloud > > needs. These projects include Compute, Identity Service, Networking, > > Image Service, Block Storage, Object Storage, Telemetry, > > Orchestration, and Database. You can install any of these projects > > separately and configure them stand-alone or as connected > > entities. This guide shows you how to install OpenStack by using > > packages on openSUSE through the Open Build Service Cloud > > repository. Explanations of configuration options and sample > > configuration files are included. > > > > > > Operations Guide > > > > This book provides information about designing and operating > OpenStack > > clouds. > > > > Cloud Administrator Guide > > > > OpenStack offers open source software for cloud administrators to > > manage and troubleshoot an OpenStack cloud. > > > > Configuration Reference > > > > This document is for system administrators who want to look up > > configuration options. It contains lists of configuration options > > available with OpenStack and uses auto-generation to generate options > > and the descriptions from the code for each project. It includes > > sample configuration files. > > > > HA Guide > > > > No abstract given. > > > > Security Guide > > > > This book provides best practices and conceptual information about > > securing an OpenStack cloud. > > > > Admin User Guide > > > > OpenStack is an open source cloud computing platform for public and > > private clouds. A series of interrelated projects deliver a cloud > > infrastructure solution. This guide shows OpenStack admin users how > to > > create and manage resources in an OpenStack cloud with the OpenStack > > dashboard or OpenStack client commands. > > > > > > End User Guide > > > > OpenStack is an open-source cloud computing platform for public and > > private clouds. A series of interrelated projects deliver a cloud > > infrastructure solution. This guide shows OpenStack end users how to > > create and manage resources in an OpenStack cloud with the OpenStack > > dashboard and OpenStack client commands. > > > > Image Guide > > > > This guide describes how to obtain, create, and modify virtual > machine > > images that are compatible with OpenStack. > > > > CLI Reference > > > > This guide documents the OpenStack command-line clients. > > > > -- > > Andreas Jaeger aj@{suse.com <http://suse.com>,opensuse.org > > <http://opensuse.org>} Twitter/Identica: jaegerandi > > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG > N?rnberg) > > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 > A126 > > > > _______________________________________________ > > Openstack-docs mailing list > > Openstack-docs at lists.openstack.org > > <mailto:Openstack-docs at lists.openstack.org> > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > > > > > > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140520/3a2550ed/attachment.html> From Randy_Perryman at Dell.com Tue May 20 13:15:59 2014 From: Randy_Perryman at Dell.com (Randy_Perryman at Dell.com) Date: Tue, 20 May 2014 08:15:59 -0500 Subject: [Openstack-docs] Target audience In-Reply-To: <CAD0KtVHWohWkRbOZag4VWhRmvyHbnxP+d-hVr1q_DGQg=Rc2Mg@mail.gmail.com> References: <537A6C5D.9090600@suse.com> <CAD0KtVHqbi84aHmu+PmmZfYZJmW918ebrHiTogfRvQSq=6e7jg@mail.gmail.com> <537B05FE.8060701@suse.com> <CAD0KtVHWohWkRbOZag4VWhRmvyHbnxP+d-hVr1q_DGQg=Rc2Mg@mail.gmail.com> Message-ID: <FC6A4A6096337446A48E483EA34F20502714236975@AUSX7MCPC102.AMER.DELL.COM> I like the persona and their needs. One item I like especially is Alice has an experience level ?many year of experience with Linux system administration?; do we need that for the others? Darren the deployer is experience with deployment of different Application and OS systems and responsible for deployment and documentation of the OpenStack Cluster prior to release to Alice. Emile the user has years of experience with using Linux based tool sets and is comfortable using both GUI and CLI based tools. I may be a little too picky here. ? -Randy From: Anne Gentle [mailto:anne at openstack.org] Sent: Tuesday, May 20, 2014 8:12 AM To: Andreas Jaeger Cc: openstack-docs at lists.openstack.org Subject: Re: [Openstack-docs] Target audience Oh we don't have to use those names in the actual metadata in the book. I was just making sure we're using personas recognized in the rest of the community. The audience statement is more like "Who this Book is For" in the Ops Guide: http://docs.openstack.org/trunk/openstack-ops/content/openstack-ops_preface.html#who-this-book-is-for On Tue, May 20, 2014 at 2:36 AM, Andreas Jaeger <aj at suse.com<mailto:aj at suse.com>> wrote: On 05/20/2014 07:18 AM, Anne Gentle wrote: > Thanks for analyzing Andreas and Randy! > > I like these three simple personas below. > > Alice the admin > Alice is an administrator who is responsible for maintaining (and > securing) the OpenStack cloud installation. She has many years of > experience with Linux systems administration. > > Darren the deployer > Darren is responsible for doing the initial OpenStack deployment on the > host machines. > Emile the end-user > Emile uses the cloud to do software development inside of the virtual > machines. She uses the command-line tools because she finds it quicker > than using the dashboard. Yes, these are fine - but let's rename Alice since Alice and Bob are the two persons used in the Security Guide explaining the two different setups. > To me, Emile is a useful persona because she uses user tools and > developer tools -- and I do see a lot of blending across user/dev tools. > Andreas, the user we haven't yet started to document for is the > application devops role, the operator who would monitor applications in > the cloud. They might be super specialized for monitoring of the VMs > themselves. > > But I'm not sure whether there's a fourth persona who does planning and > setup, what do you all think? Archie the architect? So, the OPS guide would be for Archie? > We also don't have to be super pattern-based, we can just write a > section describing the audience for each guide. ;) Andreas > > On Mon, May 19, 2014 at 3:41 PM, Andreas Jaeger <aj at suse.com<mailto:aj at suse.com> > <mailto:aj at suse.com<mailto:aj at suse.com>>> wrote: > > We had some discussion about target audience for each guide at the > OpenStack summit and Anne filed this bug: > https://bugs.launchpad.net/openstack-manuals/+bug/1319394 . As a first > step, I've went over all guides and categorized them according to target > audience and then copied all the current abstracts together. Is the > following accurate? > > Andreas > > Overview of personas/target audience: > > Operations Guide > Cloud Administrator Guide > Configuration Reference > HA Guide > Install Guide > Security Guide > Admin User Guide > > These guides target cloud administrators who sets up an OpenStack > cloud and configures the OpenStack services. > > End User Guide > Image Guide > > These guide targets users using an OpenStack cloud. > > CLI Reference > > This guide targets both cloud administrators and users using an > OpenStack cloud. > > Not covered personas: > > Developer writing applications running in an OpenStack Cloud. > > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > Detailed information - copy of current abstract: > > Install Guide > > The OpenStack? system consists of several key projects that you > install separately but that work together depending on your cloud > needs. These projects include Compute, Identity Service, Networking, > Image Service, Block Storage, Object Storage, Telemetry, > Orchestration, and Database. You can install any of these projects > separately and configure them stand-alone or as connected > entities. This guide shows you how to install OpenStack by using > packages on openSUSE through the Open Build Service Cloud > repository. Explanations of configuration options and sample > configuration files are included. > > > Operations Guide > > This book provides information about designing and operating OpenStack > clouds. > > Cloud Administrator Guide > > OpenStack offers open source software for cloud administrators to > manage and troubleshoot an OpenStack cloud. > > Configuration Reference > > This document is for system administrators who want to look up > configuration options. It contains lists of configuration options > available with OpenStack and uses auto-generation to generate options > and the descriptions from the code for each project. It includes > sample configuration files. > > HA Guide > > No abstract given. > > Security Guide > > This book provides best practices and conceptual information about > securing an OpenStack cloud. > > Admin User Guide > > OpenStack is an open source cloud computing platform for public and > private clouds. A series of interrelated projects deliver a cloud > infrastructure solution. This guide shows OpenStack admin users how to > create and manage resources in an OpenStack cloud with the OpenStack > dashboard or OpenStack client commands. > > > End User Guide > > OpenStack is an open-source cloud computing platform for public and > private clouds. A series of interrelated projects deliver a cloud > infrastructure solution. This guide shows OpenStack end users how to > create and manage resources in an OpenStack cloud with the OpenStack > dashboard and OpenStack client commands. > > Image Guide > > This guide describes how to obtain, create, and modify virtual machine > images that are compatible with OpenStack. > > CLI Reference > > This guide documents the OpenStack command-line clients. > > -- > Andreas Jaeger aj@{suse.com<http://suse.com> <http://suse.com>,opensuse.org<http://opensuse.org> > <http://opensuse.org>} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> > <mailto:Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org>> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -- Andreas Jaeger aj@{suse.com<http://suse.com>,opensuse.org<http://opensuse.org>} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140520/55c3a07f/attachment-0001.html> From doug.hellmann at dreamhost.com Tue May 20 14:31:17 2014 From: doug.hellmann at dreamhost.com (Doug Hellmann) Date: Tue, 20 May 2014 10:31:17 -0400 Subject: [Openstack-docs] [Heat][Documentation] Heat template documentation In-Reply-To: <37903930f5456fa6f09066fe41cce960@objectif-libre.com> References: <90d4482bcd0b7a52c7262631ffd3baef@objectif-libre.com> <CAD0KtVF6qnO4-Kd7ELxJZU53r7jtTSv7mCJG3ZVyJu-C+LxtYA@mail.gmail.com> <37903930f5456fa6f09066fe41cce960@objectif-libre.com> Message-ID: <CADb+p3RJ=cO0BxRsp7p=QiScS72dg5+ruz4WFZS9ZqyjE3sYcA@mail.gmail.com> On Fri, May 16, 2014 at 2:10 PM, Gauvain Pocentek <gauvain.pocentek at objectif-libre.com> wrote: > Le 2014-05-16 17:13, Anne Gentle a ?crit : > >> On Thu, May 15, 2014 at 10:34 AM, Gauvain Pocentek >> <gauvain.pocentek at objectif-libre.com> wrote: >> >>> Hello, >>> >>> This mail probably mainly concerns the doc team, but I guess that the >>> heat team wants to know what's going on. >>> >>> We've shortly discussed the state of heat documentation with Anne Gentle >>> and Andreas Jaeger yesterday, and I'd like to share what we think would be >>> nice to do. >>> >>> Currently we only have a small section in the user guide that describes >>> how to start a stack, but nothing documenting how to write templates. The >>> heat developer doc provides a good reference, but I think it's not easy to >>> use to get started. >>> >>> So the idea is to add an "OpenStack Orchestration" chapter in the user >>> guide that would document how to use a cloud with heat, and how to write >>> templates. >>> >>> I've drafted a spec to keep track of this at [0]. >> >> >> I'd like to experiment a bit with converting the End User Guide to an >> easier markup to enable more contributors to it. Perhaps bringing in >> Orchestration is a good point to do this, plus it may help address the >> auto-generation Steve mentions. >> >> The loss would be the single sourcing of the End User Guide and Admin >> User Guide as well as loss of PDF output and loss of translation. If >> these losses are worthwhile for easier maintenance and to encourage >> contributions from more cloud consumers, then I'd like to try an >> experiment with it. > > > Using RST would probably make it easier to import/include the developers' > documentation. But I'm not sure we can afford to loose the features you > mention. Translations for the user guides are very important I think. Sphinx does appear to have translation support: http://sphinx-doc.org/intl.html?highlight=translation I've never used the feature myself, so I don't know how good the workflow is. Sphinx will generate PDFs, though the LaTeX output is not as nice looking as what we get now. There's also a direct-to-pdf builder that uses rst2pdf that appears to support templates, so that might be an easier path to producing something attractive: http://ralsina.me/static/manual.pdf > > How would we review changes made in "external" repositories? The user guides > are continuously published, this means that a change done in the heat/docs/ > dir would quite quickly land on the webserver without a doc team review. I > completely trust the developers, but I'm not sure that this is the way to > go. > > >> >> The experiment would be to have a new repo set up, >> openstack/user-guide and use the docs-core team as reviewers on it. >> Convert the End User Guide from DocBook to RST and build with Sphinx. >> Use the oslosphinx tempate for output. But what I don't know is if >> it's possible to build the automated output outside of the >> openstack/heat repo, does anyone have interest in doing a proof of >> concept on this? > > > I'm not sure that this is possible, but I'm no RST expert. I'm not sure this quite answers the question, but the RST directives for auto-generating docs from code usually depend on being able to import the code. That means heat and its dependencies would need to be installed on the system where the build is performed. We accomplish this in the dev doc builds by using tox, which automatically handles the installation as part of setting up the virtualenv where the build command runs. > > >> I'd also like input on the loss of features I'm describing above. Is >> this worth experimenting with? > > > Starting this new book sounds like a lot of work. Right now I'm not > convinced it's worth it. > > Gauvain > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs From anne at openstack.org Tue May 20 22:03:46 2014 From: anne at openstack.org (Anne Gentle) Date: Tue, 20 May 2014 17:03:46 -0500 Subject: [Openstack-docs] Armed with roadmaps and bug lists, amazing docs happen Message-ID: <CAD0KtVFJJE5FruGORFrZwv6UMAxCguUDiOScShzfXiJcMYy3mw@mail.gmail.com> Hi all, I've proposed roadmaps to live in-repo for each book in the openstack-manuals repository: https://review.openstack.org/94387 https://review.openstack.org/94389 https://review.openstack.org/94386 https://review.openstack.org/94388 https://review.openstack.org/94384 https://review.openstack.org/94390 https://review.openstack.org/94385 I'd like input on the process we can implement for these roadmaps. I'd like bugs to be reserved for actual defects and blueprints to be reserved for large coordinated efforts. Roadmap tasks are additional information that enhances the particular guide targeted with the roadmap. A roadmap should give walk-up contributors a list of things they could do if they're so inclined. How can a contributor indicate they're working on a roadmap task so we avoid duplication of effort? Submit a work-in-progress patch is all I have proposed so far. Is that work-able? Let me know your thoughts on how to make a roadmap work (and don't make me set up a docs-specs repo please). :) Thanks, Anne -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140520/84673c63/attachment.html> From mkassawara at gmail.com Wed May 21 01:05:11 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Tue, 20 May 2014 19:05:11 -0600 Subject: [Openstack-docs] Armed with roadmaps and bug lists, amazing docs happen In-Reply-To: <CAD0KtVFJJE5FruGORFrZwv6UMAxCguUDiOScShzfXiJcMYy3mw@mail.gmail.com> References: <CAD0KtVFJJE5FruGORFrZwv6UMAxCguUDiOScShzfXiJcMYy3mw@mail.gmail.com> Message-ID: <CABA+jQonoYncJCfAQE2TtHk6PMPz+FcrOyoAG9TqzTV48sVzhg@mail.gmail.com> We definitely need one place (or one type of place) to find the task list for each book/document and indicate ownership for particular tasks. I like the more formal nature of including a file in each repo that requires agreement through the review process to change roadmap components. However, assigning a task to myself also requires the review process and I'm not sure we need that complexity for this particular type of change. A wiki helps the latter situation, but lacks control and history of the roadmap components. Maybe we can self-approve task assignments? On Tue, May 20, 2014 at 4:03 PM, Anne Gentle <anne at openstack.org> wrote: > Hi all, > I've proposed roadmaps to live in-repo for each book in the > openstack-manuals repository: > > https://review.openstack.org/94387 > https://review.openstack.org/94389 > https://review.openstack.org/94386 > https://review.openstack.org/94388 > https://review.openstack.org/94384 > https://review.openstack.org/94390 > https://review.openstack.org/94385 > > I'd like input on the process we can implement for these roadmaps. I'd > like bugs to be reserved for actual defects and blueprints to be reserved > for large coordinated efforts. > > Roadmap tasks are additional information that enhances the particular > guide targeted with the roadmap. A roadmap should give walk-up contributors > a list of things they could do if they're so inclined. How can a > contributor indicate they're working on a roadmap task so we avoid > duplication of effort? Submit a work-in-progress patch is all I have > proposed so far. Is that work-able? Let me know your thoughts on how to > make a roadmap work (and don't make me set up a docs-specs repo please). :) > > Thanks, > Anne > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140520/93d8d286/attachment.html> From mkassawara at gmail.com Wed May 21 01:32:57 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Tue, 20 May 2014 19:32:57 -0600 Subject: [Openstack-docs] Improvements to the Installation Guide In-Reply-To: <CABA+jQpeS+Osy3aKdUG=pTuZN6V-v0Wh52GA52AKX=ycVsMnrQ@mail.gmail.com> References: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> <53788287.4020203@b1-systems.de> <CABA+jQo1HwmujP_BL4W7AkdUs=5Zr6xDSUGD_z477UXqrxXdWw@mail.gmail.com> <CAD0KtVE+BEpom3DSwE_h-0XtCq3UwgUhbE8bgo9y731g0mQL_Q@mail.gmail.com> <CABA+jQpeS+Osy3aKdUG=pTuZN6V-v0Wh52GA52AKX=ycVsMnrQ@mail.gmail.com> Message-ID: <CABA+jQrMcV_9Ro99G_Ou5Up0jTgFBibNpvFAqgUNDYP+ExO+oQ@mail.gmail.com> Anne, I finished the etherpad-to-wiki conversion. Matt On Sun, May 18, 2014 at 5:02 PM, Matt Kassawara <mkassawara at gmail.com>wrote: > Any centralized place that we can agree upon to track activity works for > me... wiki, etherpad, bug, etc. This also applies to roadmaps. I almost > wish we could extend blueprints to handle roadmaps... essentially "living" > blueprints that remain open and flexible for the duration of a project. > > > On Sun, May 18, 2014 at 3:15 PM, Anne Gentle <anne at openstack.org> wrote: > >> >> >> >> On Sun, May 18, 2014 at 8:00 AM, Matt Kassawara <mkassawara at gmail.com>wrote: >> >>> I suppose we can use the "work items" section in the blueprint or note >>> activities on the Wiki page. >>> >> >> If you're all willing to work this way, I think it helps us know the >> "quality" of our docs set by tracking bugs as defect or inaccuracy rather >> than reorg or gap-filling. What do you think? Is it work-able to track on >> the wiki page? >> >> Let's also talk about how we can make a roadmap-per-book workable while >> still not causing duplication of effort. My original thinking is that you'd >> update the roadmap with your patch, but now I realize 2 people could work >> on a roadmap item at once without knowing the other is doing the same >> thing. Thoughts? >> Thanks, >> Anne >> >> >>> >>> On Sun, May 18, 2014 at 3:51 AM, Christian Berendt < >>> berendt at b1-systems.de> wrote: >>> >>>> On 05/18/2014 03:32 AM, Matt Kassawara wrote: >>>> > The suggested changes currently live in an Etherpad. >>>> > >>>> > https://etherpad.openstack.org/p/installation-guide-audit >>>> >>>> Will there be bugs opened first for all the changes mentioned in the >>>> Etherpad? I would like to take over some changes but I'm not sure who is >>>> responsible for the several changes at the moment and if there is >>>> somebody already assigned. >>>> >>>> Christian. >>>> >>>> -- >>>> Christian Berendt >>>> Cloud Computing Solution Architect >>>> Mail: berendt at b1-systems.de >>>> >>>> B1 Systems GmbH >>>> Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de >>>> GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 >>>> >>>> _______________________________________________ >>>> Openstack-docs mailing list >>>> Openstack-docs at lists.openstack.org >>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>>> >>> >>> >>> _______________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.openstack.org >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>> >>> >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140520/d9693f77/attachment.html> From openstack at lanabrindley.com Wed May 21 03:14:51 2014 From: openstack at lanabrindley.com (Lana Brindley) Date: Wed, 21 May 2014 13:14:51 +1000 Subject: [Openstack-docs] Armed with roadmaps and bug lists, amazing docs happen In-Reply-To: <CABA+jQonoYncJCfAQE2TtHk6PMPz+FcrOyoAG9TqzTV48sVzhg@mail.gmail.com> References: <CAD0KtVFJJE5FruGORFrZwv6UMAxCguUDiOScShzfXiJcMYy3mw@mail.gmail.com> <CABA+jQonoYncJCfAQE2TtHk6PMPz+FcrOyoAG9TqzTV48sVzhg@mail.gmail.com> Message-ID: <537C1A2B.9020105@lanabrindley.com> Yeah, I'm with Matt on this one. It doesn't really bother me where the list is stored, as long as it's easy to find, easy to update, and easy to use. Having to go through an approval/review process to assign work to yourself will just mean that people get bored and wander off in between deciding to do something, and waiting for the approval to do it. L On 21/05/14 11:05, Matt Kassawara wrote: > We definitely need one place (or one type of place) to find the task > list for each book/document and indicate ownership for particular tasks. > I like the more formal nature of including a file in each repo that > requires agreement through the review process to change roadmap > components. However, assigning a task to myself also requires the review > process and I'm not sure we need that complexity for this particular > type of change. A wiki helps the latter situation, but lacks control and > history of the roadmap components. Maybe we can self-approve task > assignments? > > > On Tue, May 20, 2014 at 4:03 PM, Anne Gentle <anne at openstack.org > <mailto:anne at openstack.org>> wrote: > > Hi all, > I've proposed roadmaps to live in-repo for each book in the > openstack-manuals repository: > > https://review.openstack.org/94387 > https://review.openstack.org/94389 > https://review.openstack.org/94386 > https://review.openstack.org/94388 > https://review.openstack.org/94384 > https://review.openstack.org/94390 > https://review.openstack.org/94385 > > I'd like input on the process we can implement for these roadmaps. > I'd like bugs to be reserved for actual defects and blueprints to be > reserved for large coordinated efforts. > > Roadmap tasks are additional information that enhances the > particular guide targeted with the roadmap. A roadmap should give > walk-up contributors a list of things they could do if they're so > inclined. How can a contributor indicate they're working on a > roadmap task so we avoid duplication of effort? Submit a > work-in-progress patch is all I have proposed so far. Is that > work-able? Let me know your thoughts on how to make a roadmap work > (and don't make me set up a docs-specs repo please). :) > > Thanks, > Anne > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > <mailto:Openstack-docs at lists.openstack.org> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -- Lana Brindley Technical Writer Rackspace Cloud Builders Australia http://lanabrindley.com From berendt at b1-systems.de Wed May 21 05:42:40 2014 From: berendt at b1-systems.de (Christian Berendt) Date: Wed, 21 May 2014 07:42:40 +0200 Subject: [Openstack-docs] Improvements to the Installation Guide In-Reply-To: <CABA+jQrMcV_9Ro99G_Ou5Up0jTgFBibNpvFAqgUNDYP+ExO+oQ@mail.gmail.com> References: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> <53788287.4020203@b1-systems.de> <CABA+jQo1HwmujP_BL4W7AkdUs=5Zr6xDSUGD_z477UXqrxXdWw@mail.gmail.com> <CAD0KtVE+BEpom3DSwE_h-0XtCq3UwgUhbE8bgo9y731g0mQL_Q@mail.gmail.com> <CABA+jQpeS+Osy3aKdUG=pTuZN6V-v0Wh52GA52AKX=ycVsMnrQ@mail.gmail.com> <CABA+jQrMcV_9Ro99G_Ou5Up0jTgFBibNpvFAqgUNDYP+ExO+oQ@mail.gmail.com> Message-ID: <537C3CD0.1000508@b1-systems.de> On 05/21/2014 03:32 AM, Matt Kassawara wrote: > I finished the etherpad-to-wiki conversion. Could you please post the URL? Don't find it right now. Thanks, Christian. -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 From lisa.m.marino at hp.com Wed May 21 09:37:05 2014 From: lisa.m.marino at hp.com (Marino, Lisa Michele) Date: Wed, 21 May 2014 09:37:05 +0000 Subject: [Openstack-docs] new contributor needs git-review setup assistance Message-ID: <65E82A781FA20A4D81EF9EA3F17C8E737812E9@G1W3641.americas.hpqcorp.net> HI there, I have just joined as a contributor and was following the repo setup instructions here: https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers I got hung up on the install git-review step, specifically "python setup.py install" command. Is there anyone who can help me with this? Thanks! Lsisa Lisa Michele Marino Information Developer HP Helion lisa.m.marino at hp.com T 001 + 412-307-4992 M 001 + 919-931-3165 Hewlett-Packard Company 5097 W Harbison Rd Pittsburgh PA 15205 USA [cid:image001.png at 01CF6887.B1D47C00] -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/171bee59/attachment.html> -------------- next part -------------- A non-text attachment was scrubbed... Name: image001.png Type: image/png Size: 3850 bytes Desc: image001.png URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/171bee59/attachment.png> From berendt at b1-systems.de Wed May 21 12:06:54 2014 From: berendt at b1-systems.de (Christian Berendt) Date: Wed, 21 May 2014 14:06:54 +0200 Subject: [Openstack-docs] new contributor needs git-review setup assistance In-Reply-To: <65E82A781FA20A4D81EF9EA3F17C8E737812E9@G1W3641.americas.hpqcorp.net> References: <65E82A781FA20A4D81EF9EA3F17C8E737812E9@G1W3641.americas.hpqcorp.net> Message-ID: <537C96DE.8020208@b1-systems.de> On 05/21/2014 11:37 AM, Marino, Lisa Michele wrote: > I got hung up on the install git-review step, specifically ?python > setup.py install? command. Is there anyone who can help me with this? Just check if your distribution already provides git-review as a distribution package (e.g. yum search git-review or zypper search git-review). Or use pip to install git-review (pip install git-review). HTH, Christian. -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 From mkassawara at gmail.com Wed May 21 12:49:10 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Wed, 21 May 2014 06:49:10 -0600 Subject: [Openstack-docs] Improvements to the Installation Guide In-Reply-To: <537C3CD0.1000508@b1-systems.de> References: <CABA+jQqux58QAavG_g-18rh+Hqw=8tvKqgwb0gx96KgTc8iTDg@mail.gmail.com> <53788287.4020203@b1-systems.de> <CABA+jQo1HwmujP_BL4W7AkdUs=5Zr6xDSUGD_z477UXqrxXdWw@mail.gmail.com> <CAD0KtVE+BEpom3DSwE_h-0XtCq3UwgUhbE8bgo9y731g0mQL_Q@mail.gmail.com> <CABA+jQpeS+Osy3aKdUG=pTuZN6V-v0Wh52GA52AKX=ycVsMnrQ@mail.gmail.com> <CABA+jQrMcV_9Ro99G_Ou5Up0jTgFBibNpvFAqgUNDYP+ExO+oQ@mail.gmail.com> <537C3CD0.1000508@b1-systems.de> Message-ID: <CABA+jQrV0AH4HMG4Vd5piPAAOY_LDb5Gbirtv0Q=MAKe8pALWg@mail.gmail.com> https://wiki.openstack.org/wiki/Documentation/InstallationGuideImprovements You can also find it in the blueprint specs. On Tue, May 20, 2014 at 11:42 PM, Christian Berendt <berendt at b1-systems.de>wrote: > On 05/21/2014 03:32 AM, Matt Kassawara wrote: > > I finished the etherpad-to-wiki conversion. > > Could you please post the URL? Don't find it right now. > > Thanks, Christian. > > -- > Christian Berendt > Cloud Computing Solution Architect > Mail: berendt at b1-systems.de > > B1 Systems GmbH > Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de > GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/17075efe/attachment.html> From berendt at b1-systems.de Wed May 21 13:41:18 2014 From: berendt at b1-systems.de (Christian Berendt) Date: Wed, 21 May 2014 15:41:18 +0200 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook Message-ID: <537CACFE.7090604@b1-systems.de> Even I like AsciiDoc I would suggest to convert the HA guide from AsciiDoc to DocBook. All other guides are written in DocBox and I don't see any benefit of keeping the HA guide in AsciiDoc. Christian. -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 From aj at suse.com Wed May 21 13:47:22 2014 From: aj at suse.com (Andreas Jaeger) Date: Wed, 21 May 2014 15:47:22 +0200 Subject: [Openstack-docs] Armed with roadmaps and bug lists, amazing docs happen In-Reply-To: <537C1A2B.9020105@lanabrindley.com> References: <CAD0KtVFJJE5FruGORFrZwv6UMAxCguUDiOScShzfXiJcMYy3mw@mail.gmail.com> <CABA+jQonoYncJCfAQE2TtHk6PMPz+FcrOyoAG9TqzTV48sVzhg@mail.gmail.com> <537C1A2B.9020105@lanabrindley.com> Message-ID: <537CAE6A.4040206@suse.com> On 05/21/2014 05:14 AM, Lana Brindley wrote: > Yeah, I'm with Matt on this one. It doesn't really bother me where the > list is stored, as long as it's easy to find, easy to update, and easy > to use. Having to go through an approval/review process to assign work > to yourself will just mean that people get bored and wander off in > between deciding to do something, and waiting for the approval to do it. And if a non-core wants to do something, one of us cores can quickly approve it... This should be a lightweight process, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Wed May 21 13:48:22 2014 From: anne at openstack.org (Anne Gentle) Date: Wed, 21 May 2014 08:48:22 -0500 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <537CACFE.7090604@b1-systems.de> References: <537CACFE.7090604@b1-systems.de> Message-ID: <CAD0KtVErmigCF2=uUW5_X49ouTx7su455yGY0hCkAuTXXBdMZQ@mail.gmail.com> Glad you brought it up again. Last time someone asked a year ago, here's how it went: http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.html Seems like a recurring theme. Let's see what happens this time around. Anne On Wed, May 21, 2014 at 8:41 AM, Christian Berendt <berendt at b1-systems.de>wrote: > Even I like AsciiDoc I would suggest to convert the HA guide from > AsciiDoc to DocBook. All other guides are written in DocBox and I don't > see any benefit of keeping the HA guide in AsciiDoc. > > Christian. > > -- > Christian Berendt > Cloud Computing Solution Architect > Mail: berendt at b1-systems.de > > B1 Systems GmbH > Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de > GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/9a78093c/attachment.html> From diane.fleming at RACKSPACE.COM Wed May 21 13:52:16 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Wed, 21 May 2014 13:52:16 +0000 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CAD0KtVErmigCF2=uUW5_X49ouTx7su455yGY0hCkAuTXXBdMZQ@mail.gmail.com> Message-ID: <CFA219AD.2D984%diane.fleming@rackspace.com> Yes please! I'm happy to convert it if everyone agrees. Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com From: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>> Date: Wednesday, May 21, 2014 8:48 AM To: Christian Berendt <berendt at b1-systems.de<mailto:berendt at b1-systems.de>> Cc: "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org>> Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook Glad you brought it up again. Last time someone asked a year ago, here's how it went: http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.html Seems like a recurring theme. Let's see what happens this time around. Anne On Wed, May 21, 2014 at 8:41 AM, Christian Berendt <berendt at b1-systems.de<mailto:berendt at b1-systems.de>> wrote: Even I like AsciiDoc I would suggest to convert the HA guide from AsciiDoc to DocBook. All other guides are written in DocBox and I don't see any benefit of keeping the HA guide in AsciiDoc. Christian. -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de<mailto:berendt at b1-systems.de> B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/46ab195c/attachment.html> From aj at suse.com Wed May 21 14:00:14 2014 From: aj at suse.com (Andreas Jaeger) Date: Wed, 21 May 2014 16:00:14 +0200 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CFA219AD.2D984%diane.fleming@rackspace.com> References: <CFA219AD.2D984%diane.fleming@rackspace.com> Message-ID: <537CB16E.5090809@suse.com> On 05/21/2014 03:52 PM, Diane Fleming wrote: > Yes please! I'm happy to convert it if everyone agrees. After working on these two patches: https://review.openstack.org/#/c/94318/ https://review.openstack.org/#/c/94319/ that workaround bugs in our asciitools conversion, I'm more than willing to go to it, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From berendt at b1-systems.de Wed May 21 14:02:02 2014 From: berendt at b1-systems.de (Christian Berendt) Date: Wed, 21 May 2014 16:02:02 +0200 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <537CB16E.5090809@suse.com> References: <CFA219AD.2D984%diane.fleming@rackspace.com> <537CB16E.5090809@suse.com> Message-ID: <537CB1DA.6000306@b1-systems.de> On 05/21/2014 04:00 PM, Andreas Jaeger wrote: > that workaround bugs in our asciitools conversion, I'm more than willing > to go to it, That's why I started this thread. I think we should not start to pollute/complicate the doc or build tools with specific workarounds for AsciiDoc when there only exists one guide using AsciiDoc. Christian. -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 From nchase at mirantis.com Wed May 21 14:22:50 2014 From: nchase at mirantis.com (Nick Chase) Date: Wed, 21 May 2014 10:22:50 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CFA219AD.2D984%diane.fleming@rackspace.com> References: <CAD0KtVErmigCF2=uUW5_X49ouTx7su455yGY0hCkAuTXXBdMZQ@mail.gmail.com> <CFA219AD.2D984%diane.fleming@rackspace.com> Message-ID: <CA+p99Gno4qkhpAVO_WrUWiiu7e-wm6qXo9yhyegzd8OjvTjn9w@mail.gmail.com> I'd be happy to do the conversion; it's something I'm familiar with, I have blocks of time where I can do it, and Diane, you can be more useful doing stuff that I can't, as a rule. That said, if you're set on doing it yourself, I won't stop you. :) Let me know. ---- Nick On Wed, May 21, 2014 at 9:52 AM, Diane Fleming <diane.fleming at rackspace.com>wrote: > Yes please! I'm happy to convert it if everyone agrees. > > > *Diane* > *----------------------------------------------* > Diane Fleming > Software Developer II - US > diane.fleming at rackspace.com > Cell 512.323.6799 > Office 512.874.1260 > Skype drfleming0227 > Google-plus diane.fleming at gmail.com > > From: Anne Gentle <anne at openstack.org> > Date: Wednesday, May 21, 2014 8:48 AM > To: Christian Berendt <berendt at b1-systems.de> > Cc: "openstack-docs at lists.openstack.org" < > Openstack-docs at lists.openstack.org> > Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to > DocBook > > Glad you brought it up again. Last time someone asked a year ago, > here's how it went: > > http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.html > > Seems like a recurring theme. Let's see what happens this time around. > > Anne > > > On Wed, May 21, 2014 at 8:41 AM, Christian Berendt <berendt at b1-systems.de>wrote: > >> Even I like AsciiDoc I would suggest to convert the HA guide from >> AsciiDoc to DocBook. All other guides are written in DocBox and I don't >> see any benefit of keeping the HA guide in AsciiDoc. >> >> Christian. >> >> -- >> Christian Berendt >> Cloud Computing Solution Architect >> Mail: berendt at b1-systems.de >> >> B1 Systems GmbH >> Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de >> GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/7711c05a/attachment.html> From sgordon at redhat.com Wed May 21 14:37:02 2014 From: sgordon at redhat.com (Steve Gordon) Date: Wed, 21 May 2014 10:37:02 -0400 (EDT) Subject: [Openstack-docs] Armed with roadmaps and bug lists, amazing docs happen In-Reply-To: <CABA+jQonoYncJCfAQE2TtHk6PMPz+FcrOyoAG9TqzTV48sVzhg@mail.gmail.com> References: <CAD0KtVFJJE5FruGORFrZwv6UMAxCguUDiOScShzfXiJcMYy3mw@mail.gmail.com> <CABA+jQonoYncJCfAQE2TtHk6PMPz+FcrOyoAG9TqzTV48sVzhg@mail.gmail.com> Message-ID: <594042561.15420012.1400683022696.JavaMail.zimbra@redhat.com> ----- Original Message ----- > From: "Matt Kassawara" <mkassawara at gmail.com> > To: "Anne Gentle" <anne at openstack.org> > Cc: openstack-docs at lists.openstack.org > Sent: Tuesday, May 20, 2014 9:05:11 PM > Subject: Re: [Openstack-docs] Armed with roadmaps and bug lists, amazing docs happen > > We definitely need one place (or one type of place) to find the task list > for each book/document and indicate ownership for particular tasks. I like > the more formal nature of including a file in each repo that requires > agreement through the review process to change roadmap components. However, > assigning a task to myself also requires the review process and I'm not > sure we need that complexity for this particular type of change. A wiki > helps the latter situation, but lacks control and history of the roadmap > components. Maybe we can self-approve task assignments? What about having a blueprint per book and using the link a bug report feature to break out tasks? -Steve From diane.fleming at RACKSPACE.COM Wed May 21 15:21:52 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Wed, 21 May 2014 15:21:52 +0000 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CA+p99Gno4qkhpAVO_WrUWiiu7e-wm6qXo9yhyegzd8OjvTjn9w@mail.gmail.com> Message-ID: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> Sure Nick, have at it! Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com From: Nick Chase <nchase at mirantis.com<mailto:nchase at mirantis.com>> Date: Wednesday, May 21, 2014 9:22 AM To: Diane Fleming <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>> Cc: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>>, Christian Berendt <berendt at b1-systems.de<mailto:berendt at b1-systems.de>>, "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org>> Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook I'd be happy to do the conversion; it's something I'm familiar with, I have blocks of time where I can do it, and Diane, you can be more useful doing stuff that I can't, as a rule. That said, if you're set on doing it yourself, I won't stop you. :) Let me know. ---- Nick On Wed, May 21, 2014 at 9:52 AM, Diane Fleming <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>> wrote: Yes please! I'm happy to convert it if everyone agrees. Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com> Cell 512.323.6799<tel:512.323.6799> Office 512.874.1260<tel:512.874.1260> Skype drfleming0227 Google-plus diane.fleming at gmail.com<mailto:diane.fleming at gmail.com> From: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>> Date: Wednesday, May 21, 2014 8:48 AM To: Christian Berendt <berendt at b1-systems.de<mailto:berendt at b1-systems.de>> Cc: "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org>> Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook Glad you brought it up again. Last time someone asked a year ago, here's how it went: http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.html Seems like a recurring theme. Let's see what happens this time around. Anne On Wed, May 21, 2014 at 8:41 AM, Christian Berendt <berendt at b1-systems.de<mailto:berendt at b1-systems.de>> wrote: Even I like AsciiDoc I would suggest to convert the HA guide from AsciiDoc to DocBook. All other guides are written in DocBox and I don't see any benefit of keeping the HA guide in AsciiDoc. Christian. -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de<mailto:berendt at b1-systems.de> B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/f4b0f4d2/attachment.html> From nchase at mirantis.com Wed May 21 15:41:39 2014 From: nchase at mirantis.com (Nicholas Chase) Date: Wed, 21 May 2014 11:41:39 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> Message-ID: <537CC933.6070106@mirantis.com> Will do! Give me a couple of days and it'll be in and ready for review. ---- Nick On 5/21/2014 11:21 AM, Diane Fleming wrote: > Sure Nick, have at it! > > /Diane/ > /----------------------------------------------/ > Diane Fleming > Software Developer II - US > diane.fleming at rackspace.com > Cell 512.323.6799 > Office 512.874.1260 > Skype drfleming0227 > Google-plus diane.fleming at gmail.com > > From: Nick Chase <nchase at mirantis.com <mailto:nchase at mirantis.com>> > Date: Wednesday, May 21, 2014 9:22 AM > To: Diane Fleming <diane.fleming at rackspace.com > <mailto:diane.fleming at rackspace.com>> > Cc: Anne Gentle <anne at openstack.org <mailto:anne at openstack.org>>, > Christian Berendt <berendt at b1-systems.de > <mailto:berendt at b1-systems.de>>, "openstack-docs at lists.openstack.org > <mailto:openstack-docs at lists.openstack.org>" > <Openstack-docs at lists.openstack.org > <mailto:Openstack-docs at lists.openstack.org>> > Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook > > I'd be happy to do the conversion; it's something I'm familiar with, I > have blocks of time where I can do it, and Diane, you can be more useful > doing stuff that I can't, as a rule. > > That said, if you're set on doing it yourself, I won't stop you. :) > > Let me know. > > ---- Nick > > > On Wed, May 21, 2014 at 9:52 AM, Diane Fleming > <diane.fleming at rackspace.com <mailto:diane.fleming at rackspace.com>> wrote: > > Yes please! I'm happy to convert it if everyone agrees. > > > /Diane/ > /----------------------------------------------/ > Diane Fleming > Software Developer II - US > diane.fleming at rackspace.com <mailto:diane.fleming at rackspace.com> > Cell 512.323.6799 <tel:512.323.6799> > Office 512.874.1260 <tel:512.874.1260> > Skype drfleming0227 > Google-plus diane.fleming at gmail.com <mailto:diane.fleming at gmail.com> > > From: Anne Gentle <anne at openstack.org <mailto:anne at openstack.org>> > Date: Wednesday, May 21, 2014 8:48 AM > To: Christian Berendt <berendt at b1-systems.de > <mailto:berendt at b1-systems.de>> > Cc: "openstack-docs at lists.openstack.org > <mailto:openstack-docs at lists.openstack.org>" > <Openstack-docs at lists.openstack.org > <mailto:Openstack-docs at lists.openstack.org>> > Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to > DocBook > > Glad you brought it up again. Last time someone asked a year ago, > here's how it went: > > http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.html > > Seems like a recurring theme. Let's see what happens this time around. > > Anne > > > On Wed, May 21, 2014 at 8:41 AM, Christian Berendt > <berendt at b1-systems.de <mailto:berendt at b1-systems.de>> wrote: > > Even I like AsciiDoc I would suggest to convert the HA guide from > AsciiDoc to DocBook. All other guides are written in DocBox and > I don't > see any benefit of keeping the HA guide in AsciiDoc. > > Christian. > > -- > Christian Berendt > Cloud Computing Solution Architect > Mail: berendt at b1-systems.de <mailto:berendt at b1-systems.de> > > B1 Systems GmbH > Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de > GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: > Ingolstadt,HRB 3537 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > <mailto:Openstack-docs at lists.openstack.org> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > <mailto:Openstack-docs at lists.openstack.org> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > From anne at openstack.org Wed May 21 15:49:21 2014 From: anne at openstack.org (Anne Gentle) Date: Wed, 21 May 2014 10:49:21 -0500 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <537CC933.6070106@mirantis.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> Message-ID: <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> Sounds good. If anyone has objections to the conversion, please engage in the review. Thanks, Anne On Wed, May 21, 2014 at 10:41 AM, Nicholas Chase <nchase at mirantis.com>wrote: > Will do! Give me a couple of days and it'll be in and ready for review. > > ---- Nick > > > On 5/21/2014 11:21 AM, Diane Fleming wrote: > >> Sure Nick, have at it! >> >> /Diane/ >> /----------------------------------------------/ >> >> Diane Fleming >> Software Developer II - US >> diane.fleming at rackspace.com >> Cell 512.323.6799 >> Office 512.874.1260 >> Skype drfleming0227 >> Google-plus diane.fleming at gmail.com >> >> From: Nick Chase <nchase at mirantis.com <mailto:nchase at mirantis.com>> >> >> Date: Wednesday, May 21, 2014 9:22 AM >> To: Diane Fleming <diane.fleming at rackspace.com >> <mailto:diane.fleming at rackspace.com>> >> Cc: Anne Gentle <anne at openstack.org <mailto:anne at openstack.org>>, >> Christian Berendt <berendt at b1-systems.de >> <mailto:berendt at b1-systems.de>>, "openstack-docs at lists.openstack.org >> <mailto:openstack-docs at lists.openstack.org>" >> <Openstack-docs at lists.openstack.org >> <mailto:Openstack-docs at lists.openstack.org>> >> >> Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to >> DocBook >> >> I'd be happy to do the conversion; it's something I'm familiar with, I >> have blocks of time where I can do it, and Diane, you can be more useful >> doing stuff that I can't, as a rule. >> >> That said, if you're set on doing it yourself, I won't stop you. :) >> >> Let me know. >> >> ---- Nick >> >> >> On Wed, May 21, 2014 at 9:52 AM, Diane Fleming >> <diane.fleming at rackspace.com <mailto:diane.fleming at rackspace.com>> wrote: >> >> Yes please! I'm happy to convert it if everyone agrees. >> >> >> /Diane/ >> /----------------------------------------------/ >> >> Diane Fleming >> Software Developer II - US >> diane.fleming at rackspace.com <mailto:diane.fleming at rackspace.com> >> Cell 512.323.6799 <tel:512.323.6799> >> Office 512.874.1260 <tel:512.874.1260> >> Skype drfleming0227 >> Google-plus diane.fleming at gmail.com <mailto:diane.fleming at gmail.com> >> >> From: Anne Gentle <anne at openstack.org <mailto:anne at openstack.org>> >> >> Date: Wednesday, May 21, 2014 8:48 AM >> To: Christian Berendt <berendt at b1-systems.de >> <mailto:berendt at b1-systems.de>> >> Cc: "openstack-docs at lists.openstack.org >> <mailto:openstack-docs at lists.openstack.org>" >> <Openstack-docs at lists.openstack.org >> <mailto:Openstack-docs at lists.openstack.org>> >> >> Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to >> DocBook >> >> Glad you brought it up again. Last time someone asked a year ago, >> here's how it went: >> >> http://lists.openstack.org/pipermail/openstack-docs/2013- >> May/001630.html >> >> Seems like a recurring theme. Let's see what happens this time around. >> >> Anne >> >> >> On Wed, May 21, 2014 at 8:41 AM, Christian Berendt >> <berendt at b1-systems.de <mailto:berendt at b1-systems.de>> wrote: >> >> Even I like AsciiDoc I would suggest to convert the HA guide from >> AsciiDoc to DocBook. All other guides are written in DocBox and >> I don't >> see any benefit of keeping the HA guide in AsciiDoc. >> >> Christian. >> >> -- >> Christian Berendt >> Cloud Computing Solution Architect >> Mail: berendt at b1-systems.de <mailto:berendt at b1-systems.de> >> >> >> B1 Systems GmbH >> Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de >> GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: >> Ingolstadt,HRB 3537 >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> <mailto:Openstack-docs at lists.openstack.org> >> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/ >> openstack-docs >> >> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> <mailto:Openstack-docs at lists.openstack.org> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> >> -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/ace962ec/attachment.html> From mkassawara at gmail.com Wed May 21 15:58:54 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Wed, 21 May 2014 09:58:54 -0600 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> Message-ID: <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> Shall we play pin the -1 on the patch? :) On Wed, May 21, 2014 at 9:49 AM, Anne Gentle <anne at openstack.org> wrote: > Sounds good. If anyone has objections to the conversion, please engage in > the review. > Thanks, > Anne > > > On Wed, May 21, 2014 at 10:41 AM, Nicholas Chase <nchase at mirantis.com>wrote: > >> Will do! Give me a couple of days and it'll be in and ready for review. >> >> ---- Nick >> >> >> On 5/21/2014 11:21 AM, Diane Fleming wrote: >> >>> Sure Nick, have at it! >>> >>> /Diane/ >>> /----------------------------------------------/ >>> >>> Diane Fleming >>> Software Developer II - US >>> diane.fleming at rackspace.com >>> Cell 512.323.6799 >>> Office 512.874.1260 >>> Skype drfleming0227 >>> Google-plus diane.fleming at gmail.com >>> >>> From: Nick Chase <nchase at mirantis.com <mailto:nchase at mirantis.com>> >>> >>> Date: Wednesday, May 21, 2014 9:22 AM >>> To: Diane Fleming <diane.fleming at rackspace.com >>> <mailto:diane.fleming at rackspace.com>> >>> Cc: Anne Gentle <anne at openstack.org <mailto:anne at openstack.org>>, >>> Christian Berendt <berendt at b1-systems.de >>> <mailto:berendt at b1-systems.de>>, "openstack-docs at lists.openstack.org >>> <mailto:openstack-docs at lists.openstack.org>" >>> <Openstack-docs at lists.openstack.org >>> <mailto:Openstack-docs at lists.openstack.org>> >>> >>> Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to >>> DocBook >>> >>> I'd be happy to do the conversion; it's something I'm familiar with, I >>> have blocks of time where I can do it, and Diane, you can be more useful >>> doing stuff that I can't, as a rule. >>> >>> That said, if you're set on doing it yourself, I won't stop you. :) >>> >>> Let me know. >>> >>> ---- Nick >>> >>> >>> On Wed, May 21, 2014 at 9:52 AM, Diane Fleming >>> <diane.fleming at rackspace.com <mailto:diane.fleming at rackspace.com>> >>> wrote: >>> >>> Yes please! I'm happy to convert it if everyone agrees. >>> >>> >>> /Diane/ >>> /----------------------------------------------/ >>> >>> Diane Fleming >>> Software Developer II - US >>> diane.fleming at rackspace.com <mailto:diane.fleming at rackspace.com> >>> Cell 512.323.6799 <tel:512.323.6799> >>> Office 512.874.1260 <tel:512.874.1260> >>> Skype drfleming0227 >>> Google-plus diane.fleming at gmail.com <mailto:diane.fleming at gmail.com> >>> >>> From: Anne Gentle <anne at openstack.org <mailto:anne at openstack.org>> >>> >>> Date: Wednesday, May 21, 2014 8:48 AM >>> To: Christian Berendt <berendt at b1-systems.de >>> <mailto:berendt at b1-systems.de>> >>> Cc: "openstack-docs at lists.openstack.org >>> <mailto:openstack-docs at lists.openstack.org>" >>> <Openstack-docs at lists.openstack.org >>> <mailto:Openstack-docs at lists.openstack.org>> >>> >>> Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to >>> DocBook >>> >>> Glad you brought it up again. Last time someone asked a year ago, >>> here's how it went: >>> >>> http://lists.openstack.org/pipermail/openstack-docs/2013- >>> May/001630.html >>> >>> Seems like a recurring theme. Let's see what happens this time >>> around. >>> >>> Anne >>> >>> >>> On Wed, May 21, 2014 at 8:41 AM, Christian Berendt >>> <berendt at b1-systems.de <mailto:berendt at b1-systems.de>> wrote: >>> >>> Even I like AsciiDoc I would suggest to convert the HA guide from >>> AsciiDoc to DocBook. All other guides are written in DocBox and >>> I don't >>> see any benefit of keeping the HA guide in AsciiDoc. >>> >>> Christian. >>> >>> -- >>> Christian Berendt >>> Cloud Computing Solution Architect >>> Mail: berendt at b1-systems.de <mailto:berendt at b1-systems.de> >>> >>> >>> B1 Systems GmbH >>> Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de >>> GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: >>> Ingolstadt,HRB 3537 >>> >>> _______________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.openstack.org >>> <mailto:Openstack-docs at lists.openstack.org> >>> >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/ >>> openstack-docs >>> >>> >>> >>> _______________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.openstack.org >>> <mailto:Openstack-docs at lists.openstack.org> >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>> >>> >>> > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/b11f3eb6/attachment-0001.html> From nchase at mirantis.com Wed May 21 16:00:46 2014 From: nchase at mirantis.com (Nicholas Chase) Date: Wed, 21 May 2014 12:00:46 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> Message-ID: <537CCDAE.50305@mirantis.com> Only if I get to return the favor. :) ---- Nick On 5/21/2014 11:58 AM, Matt Kassawara wrote: > Shall we play pin the -1 on the patch? :) > > > On Wed, May 21, 2014 at 9:49 AM, Anne Gentle <anne at openstack.org > <mailto:anne at openstack.org>> wrote: > > Sounds good. If anyone has objections to the conversion, please > engage in the review. > Thanks, > Anne > > > On Wed, May 21, 2014 at 10:41 AM, Nicholas Chase > <nchase at mirantis.com <mailto:nchase at mirantis.com>> wrote: > > Will do! Give me a couple of days and it'll be in and ready for > review. > > ---- Nick > > > On 5/21/2014 11:21 AM, Diane Fleming wrote: > > Sure Nick, have at it! > > /Diane/ > /-----------------------------__-----------------/ > > Diane Fleming > Software Developer II - US > diane.fleming at rackspace.com <mailto:diane.fleming at rackspace.com> > Cell 512.323.6799 <tel:512.323.6799> > Office 512.874.1260 <tel:512.874.1260> > Skype drfleming0227 > Google-plus diane.fleming at gmail.com > <mailto:diane.fleming at gmail.com> > > From: Nick Chase <nchase at mirantis.com > <mailto:nchase at mirantis.com> <mailto:nchase at mirantis.com > <mailto:nchase at mirantis.com>>> > > Date: Wednesday, May 21, 2014 9:22 AM > To: Diane Fleming <diane.fleming at rackspace.com > <mailto:diane.fleming at rackspace.com> > <mailto:diane.fleming at __rackspace.com > <mailto:diane.fleming at rackspace.com>>> > Cc: Anne Gentle <anne at openstack.org > <mailto:anne at openstack.org> <mailto:anne at openstack.org > <mailto:anne at openstack.org>>>, > Christian Berendt <berendt at b1-systems.de > <mailto:berendt at b1-systems.de> > <mailto:berendt at b1-systems.de > <mailto:berendt at b1-systems.de>>__>, > "openstack-docs at lists.__openstack.org > <mailto:openstack-docs at lists.openstack.org> > <mailto:openstack-docs at lists.__openstack.org > <mailto:openstack-docs at lists.openstack.org>>" > <Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org> > <mailto:Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org>>> > > Subject: Re: [Openstack-docs] convert the HA guide from > AsciiDoc to DocBook > > I'd be happy to do the conversion; it's something I'm > familiar with, I > have blocks of time where I can do it, and Diane, you can be > more useful > doing stuff that I can't, as a rule. > > That said, if you're set on doing it yourself, I won't stop > you. :) > > Let me know. > > ---- Nick > > > On Wed, May 21, 2014 at 9:52 AM, Diane Fleming > <diane.fleming at rackspace.com > <mailto:diane.fleming at rackspace.com> > <mailto:diane.fleming at __rackspace.com > <mailto:diane.fleming at rackspace.com>>> wrote: > > Yes please! I'm happy to convert it if everyone agrees. > > > /Diane/ > /-----------------------------__-----------------/ > > Diane Fleming > Software Developer II - US > diane.fleming at rackspace.com > <mailto:diane.fleming at rackspace.com> > <mailto:diane.fleming at __rackspace.com > <mailto:diane.fleming at rackspace.com>> > Cell 512.323.6799 <tel:512.323.6799> <tel:512.323.6799 > <tel:512.323.6799>> > Office 512.874.1260 <tel:512.874.1260> > <tel:512.874.1260 <tel:512.874.1260>> > Skype drfleming0227 > Google-plus diane.fleming at gmail.com > <mailto:diane.fleming at gmail.com> > <mailto:diane.fleming at gmail.__com > <mailto:diane.fleming at gmail.com>> > > From: Anne Gentle <anne at openstack.org > <mailto:anne at openstack.org> <mailto:anne at openstack.org > <mailto:anne at openstack.org>>> > > Date: Wednesday, May 21, 2014 8:48 AM > To: Christian Berendt <berendt at b1-systems.de > <mailto:berendt at b1-systems.de> > <mailto:berendt at b1-systems.de > <mailto:berendt at b1-systems.de>>__> > Cc: "openstack-docs at lists.__openstack.org > <mailto:openstack-docs at lists.openstack.org> > <mailto:openstack-docs at lists.__openstack.org > <mailto:openstack-docs at lists.openstack.org>>" > <Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org> > <mailto:Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org>>> > > Subject: Re: [Openstack-docs] convert the HA guide from > AsciiDoc to > DocBook > > Glad you brought it up again. Last time someone asked a > year ago, > here's how it went: > > http://lists.openstack.org/__pipermail/openstack-docs/2013-__May/001630.html > <http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.html> > > Seems like a recurring theme. Let's see what happens > this time around. > > Anne > > > On Wed, May 21, 2014 at 8:41 AM, Christian Berendt > <berendt at b1-systems.de <mailto:berendt at b1-systems.de> > <mailto:berendt at b1-systems.de > <mailto:berendt at b1-systems.de>>__> wrote: > > Even I like AsciiDoc I would suggest to convert the > HA guide from > AsciiDoc to DocBook. All other guides are written > in DocBox and > I don't > see any benefit of keeping the HA guide in AsciiDoc. > > Christian. > > -- > Christian Berendt > Cloud Computing Solution Architect > Mail: berendt at b1-systems.de > <mailto:berendt at b1-systems.de> <mailto:berendt at b1-systems.de > <mailto:berendt at b1-systems.de>> > > > B1 Systems GmbH > Osterfeldstra?e 7 / 85088 Vohburg / > http://www.b1-systems.de > GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: > Ingolstadt,HRB 3537 > > _________________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org> > <mailto:Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org>> > > http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs > <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> > > > > _________________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org> > <mailto:Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org>> > http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs > <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> > > > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > <mailto:Openstack-docs at lists.openstack.org> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > From emilien.macchi at enovance.com Wed May 21 16:25:41 2014 From: emilien.macchi at enovance.com (Emilien Macchi) Date: Wed, 21 May 2014 18:25:41 +0200 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <537CCDAE.50305@mirantis.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> Message-ID: <537CD385.10102@enovance.com> +1 Emilien Macchi On Wed 21 May 2014 06:00:46 PM CEST, Nicholas Chase wrote: > Only if I get to return the favor. :) > > ---- Nick > > On 5/21/2014 11:58 AM, Matt Kassawara wrote: >> Shall we play pin the -1 on the patch? :) >> >> >> On Wed, May 21, 2014 at 9:49 AM, Anne Gentle <anne at openstack.org >> <mailto:anne at openstack.org>> wrote: >> >> Sounds good. If anyone has objections to the conversion, please >> engage in the review. >> Thanks, >> Anne >> >> >> On Wed, May 21, 2014 at 10:41 AM, Nicholas Chase >> <nchase at mirantis.com <mailto:nchase at mirantis.com>> wrote: >> >> Will do! Give me a couple of days and it'll be in and ready for >> review. >> >> ---- Nick >> >> >> On 5/21/2014 11:21 AM, Diane Fleming wrote: >> >> Sure Nick, have at it! >> >> /Diane/ >> /-----------------------------__-----------------/ >> >> Diane Fleming >> Software Developer II - US >> diane.fleming at rackspace.com >> <mailto:diane.fleming at rackspace.com> >> Cell 512.323.6799 <tel:512.323.6799> >> Office 512.874.1260 <tel:512.874.1260> >> Skype drfleming0227 >> Google-plus diane.fleming at gmail.com >> <mailto:diane.fleming at gmail.com> >> >> From: Nick Chase <nchase at mirantis.com >> <mailto:nchase at mirantis.com> <mailto:nchase at mirantis.com >> <mailto:nchase at mirantis.com>>> >> >> Date: Wednesday, May 21, 2014 9:22 AM >> To: Diane Fleming <diane.fleming at rackspace.com >> <mailto:diane.fleming at rackspace.com> >> <mailto:diane.fleming at __rackspace.com >> <mailto:diane.fleming at rackspace.com>>> >> Cc: Anne Gentle <anne at openstack.org >> <mailto:anne at openstack.org> <mailto:anne at openstack.org >> <mailto:anne at openstack.org>>>, >> Christian Berendt <berendt at b1-systems.de >> <mailto:berendt at b1-systems.de> >> <mailto:berendt at b1-systems.de >> <mailto:berendt at b1-systems.de>>__>, >> "openstack-docs at lists.__openstack.org >> <mailto:openstack-docs at lists.openstack.org> >> <mailto:openstack-docs at lists.__openstack.org >> <mailto:openstack-docs at lists.openstack.org>>" >> <Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org> >> <mailto:Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org>>> >> >> Subject: Re: [Openstack-docs] convert the HA guide from >> AsciiDoc to DocBook >> >> I'd be happy to do the conversion; it's something I'm >> familiar with, I >> have blocks of time where I can do it, and Diane, you can be >> more useful >> doing stuff that I can't, as a rule. >> >> That said, if you're set on doing it yourself, I won't stop >> you. :) >> >> Let me know. >> >> ---- Nick >> >> >> On Wed, May 21, 2014 at 9:52 AM, Diane Fleming >> <diane.fleming at rackspace.com >> <mailto:diane.fleming at rackspace.com> >> <mailto:diane.fleming at __rackspace.com >> <mailto:diane.fleming at rackspace.com>>> wrote: >> >> Yes please! I'm happy to convert it if everyone agrees. >> >> >> /Diane/ >> /-----------------------------__-----------------/ >> >> Diane Fleming >> Software Developer II - US >> diane.fleming at rackspace.com >> <mailto:diane.fleming at rackspace.com> >> <mailto:diane.fleming at __rackspace.com >> <mailto:diane.fleming at rackspace.com>> >> Cell 512.323.6799 <tel:512.323.6799> <tel:512.323.6799 >> <tel:512.323.6799>> >> Office 512.874.1260 <tel:512.874.1260> >> <tel:512.874.1260 <tel:512.874.1260>> >> Skype drfleming0227 >> Google-plus diane.fleming at gmail.com >> <mailto:diane.fleming at gmail.com> >> <mailto:diane.fleming at gmail.__com >> <mailto:diane.fleming at gmail.com>> >> >> From: Anne Gentle <anne at openstack.org >> <mailto:anne at openstack.org> <mailto:anne at openstack.org >> <mailto:anne at openstack.org>>> >> >> Date: Wednesday, May 21, 2014 8:48 AM >> To: Christian Berendt <berendt at b1-systems.de >> <mailto:berendt at b1-systems.de> >> <mailto:berendt at b1-systems.de >> <mailto:berendt at b1-systems.de>>__> >> Cc: "openstack-docs at lists.__openstack.org >> <mailto:openstack-docs at lists.openstack.org> >> <mailto:openstack-docs at lists.__openstack.org >> <mailto:openstack-docs at lists.openstack.org>>" >> <Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org> >> <mailto:Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org>>> >> >> Subject: Re: [Openstack-docs] convert the HA guide from >> AsciiDoc to >> DocBook >> >> Glad you brought it up again. Last time someone asked a >> year ago, >> here's how it went: >> >> >> http://lists.openstack.org/__pipermail/openstack-docs/2013-__May/001630.html >> >> >> <http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.html> >> >> >> Seems like a recurring theme. Let's see what happens >> this time around. >> >> Anne >> >> >> On Wed, May 21, 2014 at 8:41 AM, Christian Berendt >> <berendt at b1-systems.de <mailto:berendt at b1-systems.de> >> <mailto:berendt at b1-systems.de >> <mailto:berendt at b1-systems.de>>__> wrote: >> >> Even I like AsciiDoc I would suggest to convert the >> HA guide from >> AsciiDoc to DocBook. All other guides are written >> in DocBox and >> I don't >> see any benefit of keeping the HA guide in >> AsciiDoc. >> >> Christian. >> >> -- >> Christian Berendt >> Cloud Computing Solution Architect >> Mail: berendt at b1-systems.de >> <mailto:berendt at b1-systems.de> <mailto:berendt at b1-systems.de >> <mailto:berendt at b1-systems.de>> >> >> >> B1 Systems GmbH >> Osterfeldstra?e 7 / 85088 Vohburg / >> http://www.b1-systems.de >> GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: >> Ingolstadt,HRB 3537 >> >> _________________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org> >> <mailto:Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org>> >> >> >> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs >> >> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> >> >> >> >> _________________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org> >> <mailto:Openstack-docs at lists.__openstack.org >> <mailto:Openstack-docs at lists.openstack.org>> >> >> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs >> >> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> >> >> >> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> <mailto:Openstack-docs at lists.openstack.org> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 555 bytes Desc: OpenPGP digital signature URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/f0d7941e/attachment.pgp> From aj at suse.com Wed May 21 17:49:08 2014 From: aj at suse.com (Andreas Jaeger) Date: Wed, 21 May 2014 19:49:08 +0200 Subject: [Openstack-docs] database-api publishing - ready for index.html? Message-ID: <537CE714.2000301@suse.com> The database-api is now publishing: http://docs.openstack.org/api/openstack-databases/content/overview.html Is this ready to get added to the index.html pages - or are there changes needed like removing the "review" from it? Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From annegentle at justwriteclick.com Wed May 21 18:39:25 2014 From: annegentle at justwriteclick.com (Anne Gentle) Date: Wed, 21 May 2014 13:39:25 -0500 Subject: [Openstack-docs] new contributor needs git-review setup assistance In-Reply-To: <65E82A781FA20A4D81EF9EA3F17C8E737812E9@G1W3641.americas.hpqcorp.net> References: <65E82A781FA20A4D81EF9EA3F17C8E737812E9@G1W3641.americas.hpqcorp.net> Message-ID: <C07725DE-4BDF-4D52-B66F-5E3780A45594@justwriteclick.com> On Windows, you do have to follow those steps. I have helped a fair share of people - can you give a little more info about what you see when you try to run python? You can ask more here and we'll help you through it. It probably means we have to get a working Python install on your Windows environment which is many steps. Anne Gentle Content Stacker anne at openstack.org > On May 21, 2014, at 4:37 AM, "Marino, Lisa Michele" <lisa.m.marino at hp.com> wrote: > > HI there, > > I have just joined as a contributor and was following the repo setup instructions here: > https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers > > I got hung up on the install git-review step, specifically ?python setup.py install? command. Is there anyone who can help me with this? > > Thanks! > Lsisa > > > > Lisa Michele Marino > Information Developer > HP Helion > > lisa.m.marino at hp.com > T 001 + 412-307-4992 > M 001 + 919-931-3165 > Hewlett-Packard Company > 5097 W Harbison Rd > Pittsburgh PA 15205 > USA > > <image001.png> > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140521/ddd10f1e/attachment-0001.html> From joseph.robinson at RACKSPACE.COM Wed May 21 22:59:39 2014 From: joseph.robinson at RACKSPACE.COM (Joseph Robinson) Date: Wed, 21 May 2014 22:59:39 +0000 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <537CD385.10102@enovance.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> Message-ID: <CFA36D4C.1217%joseph.robinson@rackspace.com> +1 , One point though - I am working on a patch to the HA guide at the moment. I will complete it ASAP so the conversion to XML can start. My patch: https://review.openstack.org/#/c/93856/2 -Joseph Robinson On 22/05/2014 2:25 am, "Emilien Macchi" <emilien.macchi at enovance.com> wrote: >+1 > >Emilien Macchi > >On Wed 21 May 2014 06:00:46 PM CEST, Nicholas Chase wrote: >> Only if I get to return the favor. :) >> >> ---- Nick >> >> On 5/21/2014 11:58 AM, Matt Kassawara wrote: >>> Shall we play pin the -1 on the patch? :) >>> >>> >>> On Wed, May 21, 2014 at 9:49 AM, Anne Gentle <anne at openstack.org >>> <mailto:anne at openstack.org>> wrote: >>> >>> Sounds good. If anyone has objections to the conversion, please >>> engage in the review. >>> Thanks, >>> Anne >>> >>> >>> On Wed, May 21, 2014 at 10:41 AM, Nicholas Chase >>> <nchase at mirantis.com <mailto:nchase at mirantis.com>> wrote: >>> >>> Will do! Give me a couple of days and it'll be in and ready >>>for >>> review. >>> >>> ---- Nick >>> >>> >>> On 5/21/2014 11:21 AM, Diane Fleming wrote: >>> >>> Sure Nick, have at it! >>> >>> /Diane/ >>> /-----------------------------__-----------------/ >>> >>> Diane Fleming >>> Software Developer II - US >>> diane.fleming at rackspace.com >>> <mailto:diane.fleming at rackspace.com> >>> Cell 512.323.6799 <tel:512.323.6799> >>> Office 512.874.1260 <tel:512.874.1260> >>> Skype drfleming0227 >>> Google-plus diane.fleming at gmail.com >>> <mailto:diane.fleming at gmail.com> >>> >>> From: Nick Chase <nchase at mirantis.com >>> <mailto:nchase at mirantis.com> <mailto:nchase at mirantis.com >>> <mailto:nchase at mirantis.com>>> >>> >>> Date: Wednesday, May 21, 2014 9:22 AM >>> To: Diane Fleming <diane.fleming at rackspace.com >>> <mailto:diane.fleming at rackspace.com> >>> <mailto:diane.fleming at __rackspace.com >>> <mailto:diane.fleming at rackspace.com>>> >>> Cc: Anne Gentle <anne at openstack.org >>> <mailto:anne at openstack.org> <mailto:anne at openstack.org >>> <mailto:anne at openstack.org>>>, >>> Christian Berendt <berendt at b1-systems.de >>> <mailto:berendt at b1-systems.de> >>> <mailto:berendt at b1-systems.de >>> <mailto:berendt at b1-systems.de>>__>, >>> "openstack-docs at lists.__openstack.org >>> <mailto:openstack-docs at lists.openstack.org> >>> <mailto:openstack-docs at lists.__openstack.org >>> <mailto:openstack-docs at lists.openstack.org>>" >>> <Openstack-docs at lists.__openstack.org >>> <mailto:Openstack-docs at lists.openstack.org> >>> <mailto:Openstack-docs at lists.__openstack.org >>> <mailto:Openstack-docs at lists.openstack.org>>> >>> >>> Subject: Re: [Openstack-docs] convert the HA guide from >>> AsciiDoc to DocBook >>> >>> I'd be happy to do the conversion; it's something I'm >>> familiar with, I >>> have blocks of time where I can do it, and Diane, you can >>>be >>> more useful >>> doing stuff that I can't, as a rule. >>> >>> That said, if you're set on doing it yourself, I won't stop >>> you. :) >>> >>> Let me know. >>> >>> ---- Nick >>> >>> >>> On Wed, May 21, 2014 at 9:52 AM, Diane Fleming >>> <diane.fleming at rackspace.com >>> <mailto:diane.fleming at rackspace.com> >>> <mailto:diane.fleming at __rackspace.com >>> <mailto:diane.fleming at rackspace.com>>> wrote: >>> >>> Yes please! I'm happy to convert it if everyone >>>agrees. >>> >>> >>> /Diane/ >>> /-----------------------------__-----------------/ >>> >>> Diane Fleming >>> Software Developer II - US >>> diane.fleming at rackspace.com >>> <mailto:diane.fleming at rackspace.com> >>> <mailto:diane.fleming at __rackspace.com >>> <mailto:diane.fleming at rackspace.com>> >>> Cell 512.323.6799 <tel:512.323.6799> <tel:512.323.6799 >>> <tel:512.323.6799>> >>> Office 512.874.1260 <tel:512.874.1260> >>> <tel:512.874.1260 <tel:512.874.1260>> >>> Skype drfleming0227 >>> Google-plus diane.fleming at gmail.com >>> <mailto:diane.fleming at gmail.com> >>> <mailto:diane.fleming at gmail.__com >>> <mailto:diane.fleming at gmail.com>> >>> >>> From: Anne Gentle <anne at openstack.org >>> <mailto:anne at openstack.org> <mailto:anne at openstack.org >>> <mailto:anne at openstack.org>>> >>> >>> Date: Wednesday, May 21, 2014 8:48 AM >>> To: Christian Berendt <berendt at b1-systems.de >>> <mailto:berendt at b1-systems.de> >>> <mailto:berendt at b1-systems.de >>> <mailto:berendt at b1-systems.de>>__> >>> Cc: "openstack-docs at lists.__openstack.org >>> <mailto:openstack-docs at lists.openstack.org> >>> <mailto:openstack-docs at lists.__openstack.org >>> <mailto:openstack-docs at lists.openstack.org>>" >>> <Openstack-docs at lists.__openstack.org >>> <mailto:Openstack-docs at lists.openstack.org> >>> <mailto:Openstack-docs at lists.__openstack.org >>> <mailto:Openstack-docs at lists.openstack.org>>> >>> >>> Subject: Re: [Openstack-docs] convert the HA guide >>>from >>> AsciiDoc to >>> DocBook >>> >>> Glad you brought it up again. Last time someone asked >>>a >>> year ago, >>> here's how it went: >>> >>> >>> >>>http://lists.openstack.org/__pipermail/openstack-docs/2013-__May/001630. >>>html >>> >>> >>> >>><http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.htm >>>l> >>> >>> >>> Seems like a recurring theme. Let's see what happens >>> this time around. >>> >>> Anne >>> >>> >>> On Wed, May 21, 2014 at 8:41 AM, Christian Berendt >>> <berendt at b1-systems.de <mailto:berendt at b1-systems.de> >>> <mailto:berendt at b1-systems.de >>> <mailto:berendt at b1-systems.de>>__> wrote: >>> >>> Even I like AsciiDoc I would suggest to convert >>>the >>> HA guide from >>> AsciiDoc to DocBook. All other guides are written >>> in DocBox and >>> I don't >>> see any benefit of keeping the HA guide in >>> AsciiDoc. >>> >>> Christian. >>> >>> -- >>> Christian Berendt >>> Cloud Computing Solution Architect >>> Mail: berendt at b1-systems.de >>> <mailto:berendt at b1-systems.de> >>><mailto:berendt at b1-systems.de >>> <mailto:berendt at b1-systems.de>> >>> >>> >>> B1 Systems GmbH >>> Osterfeldstra?e 7 / 85088 Vohburg / >>> http://www.b1-systems.de >>> GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: >>> Ingolstadt,HRB 3537 >>> >>> _________________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.__openstack.org >>> <mailto:Openstack-docs at lists.openstack.org> >>> <mailto:Openstack-docs at lists.__openstack.org >>> <mailto:Openstack-docs at lists.openstack.org>> >>> >>> >>> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs >>> >>> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> >>> >>> >>> >>> _________________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.__openstack.org >>> <mailto:Openstack-docs at lists.openstack.org> >>> <mailto:Openstack-docs at lists.__openstack.org >>> <mailto:Openstack-docs at lists.openstack.org>> >>> >>> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs >>> >>> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> >>> >>> >>> >>> >>> _______________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.openstack.org >>> <mailto:Openstack-docs at lists.openstack.org> >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>> >>> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > From jidawanghao at 163.com Thu May 22 07:06:28 2014 From: jidawanghao at 163.com (1) Date: Thu, 22 May 2014 15:06:28 +0800 (CST) Subject: [Openstack-docs] one question ,and some errors you got Message-ID: <5ca52de8.7998.14622c0a25c.Coremail.jidawanghao@163.com> one question Perhaps, I didn't understand why shall we change the IP address of both eth0 and eth1, with this action , the compute1 node may not have the acceptable to keep conncetion with the external networking , and most important of all, it may be influence the apt-get install action or apt-get update or ap-get upgrade action. Need anyone's reply. One fans coming from China, Peony city. some errors I found, but I'm angry about your website's action to delete my comment written in Chinese. ????8??????/etc/ntp.conf?????server?? ?9??OpenStack packages,3. ???????????key???????key????? gpg ?keyserver pgpkeys.mit.edu ?recv-key ???key???64AA94D00B849883? gpg ?a ?export???key???64AA94D00B849883? | apt-key add - ?11??20???????????????????????????????????? ?29??For example: #glance image-create ?name=?CirrOS 0.3.1? ?disk-format=qcow2 \--container-format=bare ?is-public=true < cirros-0.3.1-x86_64-disk.img ????????????HTTP 500?????????27?2. Respond to prompts for database management????????You must also select the caching type.???????You must select the caching type.????????caching?????????keystone????????????????????????/etc/glance/api.conf?/etc/glance/registry.conf??debug = true?????????????/var/log/glance/api.log?/var/log/glance/registry.log? -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140522/13c3c2ac/attachment.html> From aj at suse.com Thu May 22 15:01:05 2014 From: aj at suse.com (Andreas Jaeger) Date: Thu, 22 May 2014 17:01:05 +0200 Subject: [Openstack-docs] Japanese Security Guide fails to build Message-ID: <537E1131.2070706@suse.com> We now check the translations in the gate and I noticed that the Security Guide fails to build: https://bugs.launchpad.net/openstack-i18n/+bug/1322224 This looks some tools issue, any help on how to fix this is welcome! Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Thu May 22 15:11:02 2014 From: aj at suse.com (Andreas Jaeger) Date: Thu, 22 May 2014 17:11:02 +0200 Subject: [Openstack-docs] one question ,and some errors you got In-Reply-To: <5ca52de8.7998.14622c0a25c.Coremail.jidawanghao@163.com> References: <5ca52de8.7998.14622c0a25c.Coremail.jidawanghao@163.com> Message-ID: <537E1386.4020605@suse.com> On 05/22/2014 09:06 AM, 1 wrote: > one question > Perhaps, I didn't understand why shall we change the IP address of both > eth0 and eth1, with this action , the compute1 node may not have the > acceptable to keep conncetion with the external networking , and most > important of all, it may be influence the apt-get install action or > apt-get update or ap-get upgrade action. Need anyone's reply. One fans > coming from China, Peony city. > > some errors I found, but I'm angry about your website's action to delete > my comment written in Chinese. It wasn't the website, it was me. I didn't think you really wanted to tell everybody your phone number and non-English comments will not help you at all, since most of us cant't read them, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Thu May 22 18:55:32 2014 From: aj at suse.com (Andreas Jaeger) Date: Thu, 22 May 2014 20:55:32 +0200 Subject: [Openstack-docs] [Openstack-i18n] Translation gate for doc jobs In-Reply-To: <537A42FA.4000302@suse.com> References: <5375284F.3030208@suse.com> <CAD0KtVFooB-KqsYe82Rm1kQ0qVimv8asDK7Sd3COHUWBzVD6Pg@mail.gmail.com> <537A42FA.4000302@suse.com> Message-ID: <537E4824.7090701@suse.com> The jobs are running, and I've started documenting this here: https://wiki.openstack.org/wiki/Documentation/Builds#Gates Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Thu May 22 20:49:11 2014 From: anne at openstack.org (Anne Gentle) Date: Thu, 22 May 2014 15:49:11 -0500 Subject: [Openstack-docs] database-api publishing - ready for index.html? In-Reply-To: <537CE714.2000301@suse.com> References: <537CE714.2000301@suse.com> Message-ID: <CAD0KtVEbXv+q=Xhwo4zM_64CZanfFq7B-SFGdqUOANjnLkbDqg@mail.gmail.com> Hi Andreas, The trove team wanted to move the source from database-api to their trove repo. I'd like to publish after that happens if possible. They can better keep their examples updated this way. Did someone request the build from database-api? The "review" watermark makes me think that the move should happen by the team so they can ensure that accurate information is being published. Any insights on the request and timing? Thanks, Anne On Wed, May 21, 2014 at 12:49 PM, Andreas Jaeger <aj at suse.com> wrote: > The database-api is now publishing: > > http://docs.openstack.org/api/openstack-databases/content/overview.html > > Is this ready to get added to the index.html pages - or are there > changes needed like removing the "review" from it? > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140522/4e30b39e/attachment.html> From nikhil at manchanda.me Thu May 22 22:06:17 2014 From: nikhil at manchanda.me (Nikhil Manchanda) Date: Thu, 22 May 2014 18:06:17 -0400 Subject: [Openstack-docs] database-api publishing - ready for index.html? In-Reply-To: <CAD0KtVEbXv+q=Xhwo4zM_64CZanfFq7B-SFGdqUOANjnLkbDqg@mail.gmail.com> References: <537CE714.2000301@suse.com> <CAD0KtVEbXv+q=Xhwo4zM_64CZanfFq7B-SFGdqUOANjnLkbDqg@mail.gmail.com> Message-ID: <CAMt+b=mmHsb6=LR1dx7HnkK6YrsVg7JTEn3S=Di+85p8x23BLw@mail.gmail.com> Hi Anne / Andreas: The trove team (thanks to Tim! (grapex)) has already landed the change to move the api-docs from the openstack/database-api to the openstack/trove repository. Andreas can you please clarify if the docs in this review are being built from the trove repository, or the older database-api repository? If it's the former, I think we are good. Of course, I still need to get myself and a couple of other folks from Trove to go over the docs, and update it with new APIs that we have recently added (datastore / config groups). :) Still working on that. Thanks, Nikhil On Thu, May 22, 2014 at 4:49 PM, Anne Gentle <anne at openstack.org> wrote: > Hi Andreas, > > The trove team wanted to move the source from database-api to their trove > repo. I'd like to publish after that happens if possible. They can better > keep their examples updated this way. Did someone request the build from > database-api? > > The "review" watermark makes me think that the move should happen by the > team so they can ensure that accurate information is being published. Any > insights on the request and timing? > Thanks, > Anne > > > On Wed, May 21, 2014 at 12:49 PM, Andreas Jaeger <aj at suse.com> wrote: > >> The database-api is now publishing: >> >> http://docs.openstack.org/api/openstack-databases/content/overview.html >> >> Is this ready to get added to the index.html pages - or are there >> changes needed like removing the "review" from it? >> >> Andreas >> -- >> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany >> GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140522/b1198922/attachment.html> From mkassawara at gmail.com Thu May 22 23:58:38 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Thu, 22 May 2014 17:58:38 -0600 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs Message-ID: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> I found some inconsistencies with filenames and chapter/section IDs while auditing the Installation Guide. I thought I found some conventions while updating the guide for Icehouse, but can't find them now. If they exist, can someone point me to them? If not, we should develop some so we can proceed with the improvements. -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140522/b3805466/attachment.html> From aj at suse.com Fri May 23 07:13:28 2014 From: aj at suse.com (Andreas Jaeger) Date: Fri, 23 May 2014 09:13:28 +0200 Subject: [Openstack-docs] database-api publishing - ready for index.html? In-Reply-To: <CAMt+b=mmHsb6=LR1dx7HnkK6YrsVg7JTEn3S=Di+85p8x23BLw@mail.gmail.com> References: <537CE714.2000301@suse.com> <CAD0KtVEbXv+q=Xhwo4zM_64CZanfFq7B-SFGdqUOANjnLkbDqg@mail.gmail.com> <CAMt+b=mmHsb6=LR1dx7HnkK6YrsVg7JTEn3S=Di+85p8x23BLw@mail.gmail.com> Message-ID: <537EF518.5000107@suse.com> On 05/23/2014 12:06 AM, Nikhil Manchanda wrote: > Hi Anne / Andreas: > > The trove team (thanks to Tim! (grapex)) has already landed the change > to move the api-docs from the openstack/database-api to the > openstack/trove repository. Andreas can you please clarify if the docs > in this review are being built from the trove repository, or the older > database-api repository? This is from openstack/trove repository, we never published database-api repository. > If it's the former, I think we are good. Btw. I just send a patch to clean up the pom: https://review.openstack.org/94989 This removes the REVIEW and the hardcoded publishing date, > Of course, I still need to get myself and a couple of other folks from > Trove to go over the docs, and update it with new APIs that we have > recently added (datastore / config groups). :) Still working on that. It also only talks about MySQL - AFAIK you support other databases as well now, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From diane.fleming at RACKSPACE.COM Fri May 23 12:45:48 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Fri, 23 May 2014 12:45:48 +0000 Subject: [Openstack-docs] database-api publishing - ready for index.html? In-Reply-To: <537EF518.5000107@suse.com> References: <537CE714.2000301@suse.com> <CAD0KtVEbXv+q=Xhwo4zM_64CZanfFq7B-SFGdqUOANjnLkbDqg@mail.gmail.com> <CAMt+b=mmHsb6=LR1dx7HnkK6YrsVg7JTEn3S=Di+85p8x23BLw@mail.gmail.com>, <537EF518.5000107@suse.com> Message-ID: <A89BAF7C-F198-4784-A144-C9E0A9920B68@RACKSPACE.COM> Can we remove database-api? Sent from my iPhone > On May 23, 2014, at 2:15 AM, "Andreas Jaeger" <aj at suse.com> wrote: > >> On 05/23/2014 12:06 AM, Nikhil Manchanda wrote: >> Hi Anne / Andreas: >> >> The trove team (thanks to Tim! (grapex)) has already landed the change >> to move the api-docs from the openstack/database-api to the >> openstack/trove repository. Andreas can you please clarify if the docs >> in this review are being built from the trove repository, or the older >> database-api repository? > > This is from openstack/trove repository, we never published database-api > repository. > >> If it's the former, I think we are good. > > Btw. I just send a patch to clean up the pom: > https://review.openstack.org/94989 > > This removes the REVIEW and the hardcoded publishing date, > >> Of course, I still need to get myself and a couple of other folks from >> Trove to go over the docs, and update it with new APIs that we have >> recently added (datastore / config groups). :) Still working on that. > > It also only talks about MySQL - AFAIK you support other databases as > well now, > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs From aj at suse.com Fri May 23 12:51:48 2014 From: aj at suse.com (Andreas Jaeger) Date: Fri, 23 May 2014 14:51:48 +0200 Subject: [Openstack-docs] database-api publishing - ready for index.html? In-Reply-To: <A89BAF7C-F198-4784-A144-C9E0A9920B68@RACKSPACE.COM> References: <537CE714.2000301@suse.com> <CAD0KtVEbXv+q=Xhwo4zM_64CZanfFq7B-SFGdqUOANjnLkbDqg@mail.gmail.com> <CAMt+b=mmHsb6=LR1dx7HnkK6YrsVg7JTEn3S=Di+85p8x23BLw@mail.gmail.com>, <537EF518.5000107@suse.com> <A89BAF7C-F198-4784-A144-C9E0A9920B68@RACKSPACE.COM> Message-ID: <537F4464.2030809@suse.com> On 05/23/2014 02:45 PM, Diane Fleming wrote: > Can we remove database-api? Yes, the repository will be moved to the attic as part of the big rename: https://review.openstack.org/94953 Andreas > Sent from my iPhone > >> On May 23, 2014, at 2:15 AM, "Andreas Jaeger" <aj at suse.com> wrote: >> >>> On 05/23/2014 12:06 AM, Nikhil Manchanda wrote: >>> Hi Anne / Andreas: >>> >>> The trove team (thanks to Tim! (grapex)) has already landed the change >>> to move the api-docs from the openstack/database-api to the >>> openstack/trove repository. Andreas can you please clarify if the docs >>> in this review are being built from the trove repository, or the older >>> database-api repository? >> >> This is from openstack/trove repository, we never published database-api >> repository. >> >>> If it's the former, I think we are good. >> >> Btw. I just send a patch to clean up the pom: >> https://review.openstack.org/94989 >> >> This removes the REVIEW and the hardcoded publishing date, >> >>> Of course, I still need to get myself and a couple of other folks from >>> Trove to go over the docs, and update it with new APIs that we have >>> recently added (datastore / config groups). :) Still working on that. >> >> It also only talks about MySQL - AFAIK you support other databases as >> well now, >> >> Andreas >> -- >> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany >> GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Fri May 23 13:03:25 2014 From: anne at openstack.org (Anne Gentle) Date: Fri, 23 May 2014 08:03:25 -0500 Subject: [Openstack-docs] database-api publishing - ready for index.html? In-Reply-To: <537F4464.2030809@suse.com> References: <537CE714.2000301@suse.com> <CAD0KtVEbXv+q=Xhwo4zM_64CZanfFq7B-SFGdqUOANjnLkbDqg@mail.gmail.com> <CAMt+b=mmHsb6=LR1dx7HnkK6YrsVg7JTEn3S=Di+85p8x23BLw@mail.gmail.com> <537EF518.5000107@suse.com> <A89BAF7C-F198-4784-A144-C9E0A9920B68@RACKSPACE.COM> <537F4464.2030809@suse.com> Message-ID: <CAD0KtVF1LaSyodUWCTo_O4VoQQpC4hDd0tRCkP86GGK9R3FyKQ@mail.gmail.com> On Fri, May 23, 2014 at 7:51 AM, Andreas Jaeger <aj at suse.com> wrote: > On 05/23/2014 02:45 PM, Diane Fleming wrote: > > Can we remove database-api? > > Yes, the repository will be moved to the attic as part of the big rename: > https://review.openstack.org/94953 > > Thanks for all of this, Andreas and Nikhil! Nice work. > Andreas > > > Sent from my iPhone > > > >> On May 23, 2014, at 2:15 AM, "Andreas Jaeger" <aj at suse.com> wrote: > >> > >>> On 05/23/2014 12:06 AM, Nikhil Manchanda wrote: > >>> Hi Anne / Andreas: > >>> > >>> The trove team (thanks to Tim! (grapex)) has already landed the change > >>> to move the api-docs from the openstack/database-api to the > >>> openstack/trove repository. Andreas can you please clarify if the docs > >>> in this review are being built from the trove repository, or the older > >>> database-api repository? > >> > >> This is from openstack/trove repository, we never published database-api > >> repository. > >> > >>> If it's the former, I think we are good. > >> > >> Btw. I just send a patch to clean up the pom: > >> https://review.openstack.org/94989 > >> > >> This removes the REVIEW and the hardcoded publishing date, > >> > >>> Of course, I still need to get myself and a couple of other folks from > >>> Trove to go over the docs, and update it with new APIs that we have > >>> recently added (datastore / config groups). :) Still working on that. > >> > >> It also only talks about MySQL - AFAIK you support other databases as > >> well now, > >> > >> Andreas > >> -- > >> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi > >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > >> GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > >> > >> _______________________________________________ > >> Openstack-docs mailing list > >> Openstack-docs at lists.openstack.org > >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > > > > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140523/f3e7e14f/attachment.html> From aj at suse.com Fri May 23 19:15:51 2014 From: aj at suse.com (Andreas Jaeger) Date: Fri, 23 May 2014 21:15:51 +0200 Subject: [Openstack-docs] Target audience In-Reply-To: <537A6C5D.9090600@suse.com> References: <537A6C5D.9090600@suse.com> Message-ID: <537F9E67.7000609@suse.com> Here's a next iteration for content - I've put it up on an etherpad for easier editing: https://etherpad.openstack.org/p/target_audience For the wiki, I would add something like the following - and if we agree on this, we can refine the target audience for each book. For writing these books, we use some simple personas: Anna the admin Anna is an administrator who is responsible for maintaining (and securing) the OpenStack cloud installation. She has many years of experience with Linux systems administration. Darren the deployer Darren is responsible for doing the initial OpenStack deployment on the host machines. Emile the end-user Emile uses the cloud to do software development inside of the virtual machines. She uses the command-line tools because she finds it quicker than using the dashboard. Otto, the devops operator Otto is the application devops operator, he runs and monitors applications in the cloud. Manual breakdown: Operations Guide Cloud Administrator Guide Admin User Guide These guides target the day to day operations of an OpenStack cloud system. Persona: Anna ------------------------ Configuration Reference HA Guide Install Guide Operations Guide These guides target cloud administrators who sets up an OpenStack cloud and configures the OpenStack services. Persona: Darren, Anna ------------------------ Security Guide This guide targets the Security Administrator of a cloud team and can be referenced to harden existing OpenStack deployments or to evaluate the security controls of OpenStack cloud providers. Persona: Anna ------------------------ End User Guide Image Guide Persona: Emile -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From mkassawara at gmail.com Sat May 24 14:45:21 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Sat, 24 May 2014 08:45:21 -0600 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> References: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> Message-ID: <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> Would consistently indicating type within an ID help clarify references? For example, chapter IDs always start with "ch_", section IDs always start with "sec_", figure IDs start with "fig_", etc. On Thu, May 22, 2014 at 5:58 PM, Matt Kassawara <mkassawara at gmail.com>wrote: > I found some inconsistencies with filenames and chapter/section IDs while > auditing the Installation Guide. I thought I found some conventions while > updating the guide for Icehouse, but can't find them now. If they exist, > can someone point me to them? If not, we should develop some so we can > proceed with the improvements. > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140524/1d209fbd/attachment.html> From nchase at mirantis.com Sun May 25 00:16:34 2014 From: nchase at mirantis.com (Nick Chase) Date: Sat, 24 May 2014 20:16:34 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CFA36D4C.1217%joseph.robinson@rackspace.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> Message-ID: <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> I'll get started on the structure and the rest of the chapters in the meantime. Question, though: I'd hate to try and put this through as one huge review; I'm thinking instead maybe one bug for the general changeover, then one bug each per chapter? I can have everything ready to go to start, and once the book framework's been merged, we can run the chapter reviews concurrently to minimize disruption. Locally, I've already got the framework in and I'm adding chapters (keeping in mind that I'll have to re-add Joseph's content when he's finished). Thoughts? ---- Nick On Wed, May 21, 2014 at 6:59 PM, Joseph Robinson < joseph.robinson at rackspace.com> wrote: > +1 , One point though - I am working on a patch to the HA guide at the > moment. I will complete it ASAP so the conversion to XML can start. > > My patch: https://review.openstack.org/#/c/93856/2 > > -Joseph Robinson > > On 22/05/2014 2:25 am, "Emilien Macchi" <emilien.macchi at enovance.com> > wrote: > > >+1 > > > >Emilien Macchi > > > >On Wed 21 May 2014 06:00:46 PM CEST, Nicholas Chase wrote: > >> Only if I get to return the favor. :) > >> > >> ---- Nick > >> > >> On 5/21/2014 11:58 AM, Matt Kassawara wrote: > >>> Shall we play pin the -1 on the patch? :) > >>> > >>> > >>> On Wed, May 21, 2014 at 9:49 AM, Anne Gentle <anne at openstack.org > >>> <mailto:anne at openstack.org>> wrote: > >>> > >>> Sounds good. If anyone has objections to the conversion, please > >>> engage in the review. > >>> Thanks, > >>> Anne > >>> > >>> > >>> On Wed, May 21, 2014 at 10:41 AM, Nicholas Chase > >>> <nchase at mirantis.com <mailto:nchase at mirantis.com>> wrote: > >>> > >>> Will do! Give me a couple of days and it'll be in and ready > >>>for > >>> review. > >>> > >>> ---- Nick > >>> > >>> > >>> On 5/21/2014 11:21 AM, Diane Fleming wrote: > >>> > >>> Sure Nick, have at it! > >>> > >>> /Diane/ > >>> /-----------------------------__-----------------/ > >>> > >>> Diane Fleming > >>> Software Developer II - US > >>> diane.fleming at rackspace.com > >>> <mailto:diane.fleming at rackspace.com> > >>> Cell 512.323.6799 <tel:512.323.6799> > >>> Office 512.874.1260 <tel:512.874.1260> > >>> Skype drfleming0227 > >>> Google-plus diane.fleming at gmail.com > >>> <mailto:diane.fleming at gmail.com> > >>> > >>> From: Nick Chase <nchase at mirantis.com > >>> <mailto:nchase at mirantis.com> <mailto:nchase at mirantis.com > >>> <mailto:nchase at mirantis.com>>> > >>> > >>> Date: Wednesday, May 21, 2014 9:22 AM > >>> To: Diane Fleming <diane.fleming at rackspace.com > >>> <mailto:diane.fleming at rackspace.com> > >>> <mailto:diane.fleming at __rackspace.com > >>> <mailto:diane.fleming at rackspace.com>>> > >>> Cc: Anne Gentle <anne at openstack.org > >>> <mailto:anne at openstack.org> <mailto:anne at openstack.org > >>> <mailto:anne at openstack.org>>>, > >>> Christian Berendt <berendt at b1-systems.de > >>> <mailto:berendt at b1-systems.de> > >>> <mailto:berendt at b1-systems.de > >>> <mailto:berendt at b1-systems.de>>__>, > >>> "openstack-docs at lists.__openstack.org > >>> <mailto:openstack-docs at lists.openstack.org> > >>> <mailto:openstack-docs at lists.__openstack.org > >>> <mailto:openstack-docs at lists.openstack.org>>" > >>> <Openstack-docs at lists.__openstack.org > >>> <mailto:Openstack-docs at lists.openstack.org> > >>> <mailto:Openstack-docs at lists.__openstack.org > >>> <mailto:Openstack-docs at lists.openstack.org>>> > >>> > >>> Subject: Re: [Openstack-docs] convert the HA guide from > >>> AsciiDoc to DocBook > >>> > >>> I'd be happy to do the conversion; it's something I'm > >>> familiar with, I > >>> have blocks of time where I can do it, and Diane, you can > >>>be > >>> more useful > >>> doing stuff that I can't, as a rule. > >>> > >>> That said, if you're set on doing it yourself, I won't stop > >>> you. :) > >>> > >>> Let me know. > >>> > >>> ---- Nick > >>> > >>> > >>> On Wed, May 21, 2014 at 9:52 AM, Diane Fleming > >>> <diane.fleming at rackspace.com > >>> <mailto:diane.fleming at rackspace.com> > >>> <mailto:diane.fleming at __rackspace.com > >>> <mailto:diane.fleming at rackspace.com>>> wrote: > >>> > >>> Yes please! I'm happy to convert it if everyone > >>>agrees. > >>> > >>> > >>> /Diane/ > >>> /-----------------------------__-----------------/ > >>> > >>> Diane Fleming > >>> Software Developer II - US > >>> diane.fleming at rackspace.com > >>> <mailto:diane.fleming at rackspace.com> > >>> <mailto:diane.fleming at __rackspace.com > >>> <mailto:diane.fleming at rackspace.com>> > >>> Cell 512.323.6799 <tel:512.323.6799> <tel: > 512.323.6799 > >>> <tel:512.323.6799>> > >>> Office 512.874.1260 <tel:512.874.1260> > >>> <tel:512.874.1260 <tel:512.874.1260>> > >>> Skype drfleming0227 > >>> Google-plus diane.fleming at gmail.com > >>> <mailto:diane.fleming at gmail.com> > >>> <mailto:diane.fleming at gmail.__com > >>> <mailto:diane.fleming at gmail.com>> > >>> > >>> From: Anne Gentle <anne at openstack.org > >>> <mailto:anne at openstack.org> <mailto:anne at openstack.org > >>> <mailto:anne at openstack.org>>> > >>> > >>> Date: Wednesday, May 21, 2014 8:48 AM > >>> To: Christian Berendt <berendt at b1-systems.de > >>> <mailto:berendt at b1-systems.de> > >>> <mailto:berendt at b1-systems.de > >>> <mailto:berendt at b1-systems.de>>__> > >>> Cc: "openstack-docs at lists.__openstack.org > >>> <mailto:openstack-docs at lists.openstack.org> > >>> <mailto:openstack-docs at lists.__openstack.org > >>> <mailto:openstack-docs at lists.openstack.org>>" > >>> <Openstack-docs at lists.__openstack.org > >>> <mailto:Openstack-docs at lists.openstack.org> > >>> <mailto:Openstack-docs at lists.__openstack.org > >>> <mailto:Openstack-docs at lists.openstack.org>>> > >>> > >>> Subject: Re: [Openstack-docs] convert the HA guide > >>>from > >>> AsciiDoc to > >>> DocBook > >>> > >>> Glad you brought it up again. Last time someone asked > >>>a > >>> year ago, > >>> here's how it went: > >>> > >>> > >>> > >>>http://lists.openstack.org/__pipermail/openstack-docs/2013-__May/001630 > . > >>>html > >>> > >>> > >>> > >>>< > http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.htm > >>>l> > >>> > >>> > >>> Seems like a recurring theme. Let's see what happens > >>> this time around. > >>> > >>> Anne > >>> > >>> > >>> On Wed, May 21, 2014 at 8:41 AM, Christian Berendt > >>> <berendt at b1-systems.de <mailto:berendt at b1-systems.de> > >>> <mailto:berendt at b1-systems.de > >>> <mailto:berendt at b1-systems.de>>__> wrote: > >>> > >>> Even I like AsciiDoc I would suggest to convert > >>>the > >>> HA guide from > >>> AsciiDoc to DocBook. All other guides are written > >>> in DocBox and > >>> I don't > >>> see any benefit of keeping the HA guide in > >>> AsciiDoc. > >>> > >>> Christian. > >>> > >>> -- > >>> Christian Berendt > >>> Cloud Computing Solution Architect > >>> Mail: berendt at b1-systems.de > >>> <mailto:berendt at b1-systems.de> > >>><mailto:berendt at b1-systems.de > >>> <mailto:berendt at b1-systems.de>> > >>> > >>> > >>> B1 Systems GmbH > >>> Osterfeldstra?e 7 / 85088 Vohburg / > >>> http://www.b1-systems.de > >>> GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: > >>> Ingolstadt,HRB 3537 > >>> > >>> _________________________________________________ > >>> Openstack-docs mailing list > >>> Openstack-docs at lists.__openstack.org > >>> <mailto:Openstack-docs at lists.openstack.org> > >>> <mailto:Openstack-docs at lists.__openstack.org > >>> <mailto:Openstack-docs at lists.openstack.org>> > >>> > >>> > >>> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs > >>> > >>> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> > >>> > >>> > >>> > >>> _________________________________________________ > >>> Openstack-docs mailing list > >>> Openstack-docs at lists.__openstack.org > >>> <mailto:Openstack-docs at lists.openstack.org> > >>> <mailto:Openstack-docs at lists.__openstack.org > >>> <mailto:Openstack-docs at lists.openstack.org>> > >>> > >>> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs > >>> > >>> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> > >>> > >>> > >>> > >>> > >>> _______________________________________________ > >>> Openstack-docs mailing list > >>> Openstack-docs at lists.openstack.org > >>> <mailto:Openstack-docs at lists.openstack.org> > >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > >>> > >>> > >> > >> _______________________________________________ > >> Openstack-docs mailing list > >> Openstack-docs at lists.openstack.org > >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140524/344c833a/attachment-0001.html> From mkassawara at gmail.com Sun May 25 02:36:42 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Sat, 24 May 2014 20:36:42 -0600 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> Message-ID: <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> I'm using a blueprint instead of bugs for the installation guide improvements. I think Anne wants to limit bugs to actual defects/inaccuracies. On Sat, May 24, 2014 at 6:16 PM, Nick Chase <nchase at mirantis.com> wrote: > I'll get started on the structure and the rest of the chapters in the > meantime. > > Question, though: I'd hate to try and put this through as one huge review; > I'm thinking instead maybe one bug for the general changeover, then one bug > each per chapter? I can have everything ready to go to start, and once the > book framework's been merged, we can run the chapter reviews concurrently > to minimize disruption. > > Locally, I've already got the framework in and I'm adding chapters > (keeping in mind that I'll have to re-add Joseph's content when he's > finished). > > Thoughts? > > ---- Nick > > > On Wed, May 21, 2014 at 6:59 PM, Joseph Robinson < > joseph.robinson at rackspace.com> wrote: > >> +1 , One point though - I am working on a patch to the HA guide at the >> moment. I will complete it ASAP so the conversion to XML can start. >> >> My patch: https://review.openstack.org/#/c/93856/2 >> >> -Joseph Robinson >> >> On 22/05/2014 2:25 am, "Emilien Macchi" <emilien.macchi at enovance.com> >> wrote: >> >> >+1 >> > >> >Emilien Macchi >> > >> >On Wed 21 May 2014 06:00:46 PM CEST, Nicholas Chase wrote: >> >> Only if I get to return the favor. :) >> >> >> >> ---- Nick >> >> >> >> On 5/21/2014 11:58 AM, Matt Kassawara wrote: >> >>> Shall we play pin the -1 on the patch? :) >> >>> >> >>> >> >>> On Wed, May 21, 2014 at 9:49 AM, Anne Gentle <anne at openstack.org >> >>> <mailto:anne at openstack.org>> wrote: >> >>> >> >>> Sounds good. If anyone has objections to the conversion, please >> >>> engage in the review. >> >>> Thanks, >> >>> Anne >> >>> >> >>> >> >>> On Wed, May 21, 2014 at 10:41 AM, Nicholas Chase >> >>> <nchase at mirantis.com <mailto:nchase at mirantis.com>> wrote: >> >>> >> >>> Will do! Give me a couple of days and it'll be in and ready >> >>>for >> >>> review. >> >>> >> >>> ---- Nick >> >>> >> >>> >> >>> On 5/21/2014 11:21 AM, Diane Fleming wrote: >> >>> >> >>> Sure Nick, have at it! >> >>> >> >>> /Diane/ >> >>> /-----------------------------__-----------------/ >> >>> >> >>> Diane Fleming >> >>> Software Developer II - US >> >>> diane.fleming at rackspace.com >> >>> <mailto:diane.fleming at rackspace.com> >> >>> Cell 512.323.6799 <tel:512.323.6799> >> >>> Office 512.874.1260 <tel:512.874.1260> >> >>> Skype drfleming0227 >> >>> Google-plus diane.fleming at gmail.com >> >>> <mailto:diane.fleming at gmail.com> >> >>> >> >>> From: Nick Chase <nchase at mirantis.com >> >>> <mailto:nchase at mirantis.com> <mailto:nchase at mirantis.com >> >>> <mailto:nchase at mirantis.com>>> >> >>> >> >>> Date: Wednesday, May 21, 2014 9:22 AM >> >>> To: Diane Fleming <diane.fleming at rackspace.com >> >>> <mailto:diane.fleming at rackspace.com> >> >>> <mailto:diane.fleming at __rackspace.com >> >>> <mailto:diane.fleming at rackspace.com>>> >> >>> Cc: Anne Gentle <anne at openstack.org >> >>> <mailto:anne at openstack.org> <mailto:anne at openstack.org >> >>> <mailto:anne at openstack.org>>>, >> >>> Christian Berendt <berendt at b1-systems.de >> >>> <mailto:berendt at b1-systems.de> >> >>> <mailto:berendt at b1-systems.de >> >>> <mailto:berendt at b1-systems.de>>__>, >> >>> "openstack-docs at lists.__openstack.org >> >>> <mailto:openstack-docs at lists.openstack.org> >> >>> <mailto:openstack-docs at lists.__openstack.org >> >>> <mailto:openstack-docs at lists.openstack.org>>" >> >>> <Openstack-docs at lists.__openstack.org >> >>> <mailto:Openstack-docs at lists.openstack.org> >> >>> <mailto:Openstack-docs at lists.__openstack.org >> >>> <mailto:Openstack-docs at lists.openstack.org>>> >> >>> >> >>> Subject: Re: [Openstack-docs] convert the HA guide from >> >>> AsciiDoc to DocBook >> >>> >> >>> I'd be happy to do the conversion; it's something I'm >> >>> familiar with, I >> >>> have blocks of time where I can do it, and Diane, you can >> >>>be >> >>> more useful >> >>> doing stuff that I can't, as a rule. >> >>> >> >>> That said, if you're set on doing it yourself, I won't >> stop >> >>> you. :) >> >>> >> >>> Let me know. >> >>> >> >>> ---- Nick >> >>> >> >>> >> >>> On Wed, May 21, 2014 at 9:52 AM, Diane Fleming >> >>> <diane.fleming at rackspace.com >> >>> <mailto:diane.fleming at rackspace.com> >> >>> <mailto:diane.fleming at __rackspace.com >> >>> <mailto:diane.fleming at rackspace.com>>> wrote: >> >>> >> >>> Yes please! I'm happy to convert it if everyone >> >>>agrees. >> >>> >> >>> >> >>> /Diane/ >> >>> /-----------------------------__-----------------/ >> >>> >> >>> Diane Fleming >> >>> Software Developer II - US >> >>> diane.fleming at rackspace.com >> >>> <mailto:diane.fleming at rackspace.com> >> >>> <mailto:diane.fleming at __rackspace.com >> >>> <mailto:diane.fleming at rackspace.com>> >> >>> Cell 512.323.6799 <tel:512.323.6799> <tel: >> 512.323.6799 >> >>> <tel:512.323.6799>> >> >>> Office 512.874.1260 <tel:512.874.1260> >> >>> <tel:512.874.1260 <tel:512.874.1260>> >> >>> Skype drfleming0227 >> >>> Google-plus diane.fleming at gmail.com >> >>> <mailto:diane.fleming at gmail.com> >> >>> <mailto:diane.fleming at gmail.__com >> >>> <mailto:diane.fleming at gmail.com>> >> >>> >> >>> From: Anne Gentle <anne at openstack.org >> >>> <mailto:anne at openstack.org> <mailto:anne at openstack.org >> >>> <mailto:anne at openstack.org>>> >> >>> >> >>> Date: Wednesday, May 21, 2014 8:48 AM >> >>> To: Christian Berendt <berendt at b1-systems.de >> >>> <mailto:berendt at b1-systems.de> >> >>> <mailto:berendt at b1-systems.de >> >>> <mailto:berendt at b1-systems.de>>__> >> >>> Cc: "openstack-docs at lists.__openstack.org >> >>> <mailto:openstack-docs at lists.openstack.org> >> >>> <mailto:openstack-docs at lists.__openstack.org >> >>> <mailto:openstack-docs at lists.openstack.org>>" >> >>> <Openstack-docs at lists.__openstack.org >> >>> <mailto:Openstack-docs at lists.openstack.org> >> >>> <mailto:Openstack-docs at lists.__openstack.org >> >>> <mailto:Openstack-docs at lists.openstack.org>>> >> >>> >> >>> Subject: Re: [Openstack-docs] convert the HA guide >> >>>from >> >>> AsciiDoc to >> >>> DocBook >> >>> >> >>> Glad you brought it up again. Last time someone asked >> >>>a >> >>> year ago, >> >>> here's how it went: >> >>> >> >>> >> >>> >> >>> >> http://lists.openstack.org/__pipermail/openstack-docs/2013-__May/001630. >> >>>html >> >>> >> >>> >> >>> >> >>>< >> http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.htm >> >>>l> >> >>> >> >>> >> >>> Seems like a recurring theme. Let's see what happens >> >>> this time around. >> >>> >> >>> Anne >> >>> >> >>> >> >>> On Wed, May 21, 2014 at 8:41 AM, Christian Berendt >> >>> <berendt at b1-systems.de <mailto:berendt at b1-systems.de >> > >> >>> <mailto:berendt at b1-systems.de >> >>> <mailto:berendt at b1-systems.de>>__> wrote: >> >>> >> >>> Even I like AsciiDoc I would suggest to convert >> >>>the >> >>> HA guide from >> >>> AsciiDoc to DocBook. All other guides are written >> >>> in DocBox and >> >>> I don't >> >>> see any benefit of keeping the HA guide in >> >>> AsciiDoc. >> >>> >> >>> Christian. >> >>> >> >>> -- >> >>> Christian Berendt >> >>> Cloud Computing Solution Architect >> >>> Mail: berendt at b1-systems.de >> >>> <mailto:berendt at b1-systems.de> >> >>><mailto:berendt at b1-systems.de >> >>> <mailto:berendt at b1-systems.de>> >> >>> >> >>> >> >>> B1 Systems GmbH >> >>> Osterfeldstra?e 7 / 85088 Vohburg / >> >>> http://www.b1-systems.de >> >>> GF: Ralph Dehner / Unternehmenssitz: Vohburg / >> AG: >> >>> Ingolstadt,HRB 3537 >> >>> >> >>> _________________________________________________ >> >>> Openstack-docs mailing list >> >>> Openstack-docs at lists.__openstack.org >> >>> <mailto:Openstack-docs at lists.openstack.org> >> >>> <mailto:Openstack-docs at lists.__openstack.org >> >>> <mailto:Openstack-docs at lists.openstack.org>> >> >>> >> >>> >> >>> >> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs >> >>> >> >>> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> >> >>> >> >>> >> >>> >> >>> _________________________________________________ >> >>> Openstack-docs mailing list >> >>> Openstack-docs at lists.__openstack.org >> >>> <mailto:Openstack-docs at lists.openstack.org> >> >>> <mailto:Openstack-docs at lists.__openstack.org >> >>> <mailto:Openstack-docs at lists.openstack.org>> >> >>> >> >>> >> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs >> >>> >> >>> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> >> >>> >> >>> >> >>> >> >>> >> >>> _______________________________________________ >> >>> Openstack-docs mailing list >> >>> Openstack-docs at lists.openstack.org >> >>> <mailto:Openstack-docs at lists.openstack.org> >> >>> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >>> >> >>> >> >> >> >> _______________________________________________ >> >> Openstack-docs mailing list >> >> Openstack-docs at lists.openstack.org >> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> > >> >> > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140524/0ba0f678/attachment-0001.html> From nchase at mirantis.com Sun May 25 05:51:39 2014 From: nchase at mirantis.com (Nick Chase) Date: Sun, 25 May 2014 01:51:39 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> Message-ID: <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> Great. Done. https://blueprints.launchpad.net/openstack-manuals/+spec/convert-ha-guide-to-docbook Joseph, do you know when you'll be done with the list fixes? I don't know how to make that numbered list work right in ASCIIDoc, but I do know how to make it work in Docbook, so we could also, if there's agreement here, accept the patch as it is and I'll incorporate it and fix it immediately in the Docbook. ---- Nick On Sat, May 24, 2014 at 10:36 PM, Matt Kassawara <mkassawara at gmail.com>wrote: > I'm using a blueprint instead of bugs for the installation guide > improvements. I think Anne wants to limit bugs to actual > defects/inaccuracies. > > > On Sat, May 24, 2014 at 6:16 PM, Nick Chase <nchase at mirantis.com> wrote: > >> I'll get started on the structure and the rest of the chapters in the >> meantime. >> >> Question, though: I'd hate to try and put this through as one huge >> review; I'm thinking instead maybe one bug for the general changeover, then >> one bug each per chapter? I can have everything ready to go to start, and >> once the book framework's been merged, we can run the chapter reviews >> concurrently to minimize disruption. >> >> Locally, I've already got the framework in and I'm adding chapters >> (keeping in mind that I'll have to re-add Joseph's content when he's >> finished). >> >> Thoughts? >> >> ---- Nick >> >> >> On Wed, May 21, 2014 at 6:59 PM, Joseph Robinson < >> joseph.robinson at rackspace.com> wrote: >> >>> +1 , One point though - I am working on a patch to the HA guide at the >>> moment. I will complete it ASAP so the conversion to XML can start. >>> >>> My patch: https://review.openstack.org/#/c/93856/2 >>> >>> -Joseph Robinson >>> >>> On 22/05/2014 2:25 am, "Emilien Macchi" <emilien.macchi at enovance.com> >>> wrote: >>> >>> >+1 >>> > >>> >Emilien Macchi >>> > >>> >On Wed 21 May 2014 06:00:46 PM CEST, Nicholas Chase wrote: >>> >> Only if I get to return the favor. :) >>> >> >>> >> ---- Nick >>> >> >>> >> On 5/21/2014 11:58 AM, Matt Kassawara wrote: >>> >>> Shall we play pin the -1 on the patch? :) >>> >>> >>> >>> >>> >>> On Wed, May 21, 2014 at 9:49 AM, Anne Gentle <anne at openstack.org >>> >>> <mailto:anne at openstack.org>> wrote: >>> >>> >>> >>> Sounds good. If anyone has objections to the conversion, please >>> >>> engage in the review. >>> >>> Thanks, >>> >>> Anne >>> >>> >>> >>> >>> >>> On Wed, May 21, 2014 at 10:41 AM, Nicholas Chase >>> >>> <nchase at mirantis.com <mailto:nchase at mirantis.com>> wrote: >>> >>> >>> >>> Will do! Give me a couple of days and it'll be in and ready >>> >>>for >>> >>> review. >>> >>> >>> >>> ---- Nick >>> >>> >>> >>> >>> >>> On 5/21/2014 11:21 AM, Diane Fleming wrote: >>> >>> >>> >>> Sure Nick, have at it! >>> >>> >>> >>> /Diane/ >>> >>> /-----------------------------__-----------------/ >>> >>> >>> >>> Diane Fleming >>> >>> Software Developer II - US >>> >>> diane.fleming at rackspace.com >>> >>> <mailto:diane.fleming at rackspace.com> >>> >>> Cell 512.323.6799 <tel:512.323.6799> >>> >>> Office 512.874.1260 <tel:512.874.1260> >>> >>> Skype drfleming0227 >>> >>> Google-plus diane.fleming at gmail.com >>> >>> <mailto:diane.fleming at gmail.com> >>> >>> >>> >>> From: Nick Chase <nchase at mirantis.com >>> >>> <mailto:nchase at mirantis.com> <mailto:nchase at mirantis.com >>> >>> <mailto:nchase at mirantis.com>>> >>> >>> >>> >>> Date: Wednesday, May 21, 2014 9:22 AM >>> >>> To: Diane Fleming <diane.fleming at rackspace.com >>> >>> <mailto:diane.fleming at rackspace.com> >>> >>> <mailto:diane.fleming at __rackspace.com >>> >>> <mailto:diane.fleming at rackspace.com>>> >>> >>> Cc: Anne Gentle <anne at openstack.org >>> >>> <mailto:anne at openstack.org> <mailto:anne at openstack.org >>> >>> <mailto:anne at openstack.org>>>, >>> >>> Christian Berendt <berendt at b1-systems.de >>> >>> <mailto:berendt at b1-systems.de> >>> >>> <mailto:berendt at b1-systems.de >>> >>> <mailto:berendt at b1-systems.de>>__>, >>> >>> "openstack-docs at lists.__openstack.org >>> >>> <mailto:openstack-docs at lists.openstack.org> >>> >>> <mailto:openstack-docs at lists.__openstack.org >>> >>> <mailto:openstack-docs at lists.openstack.org>>" >>> >>> <Openstack-docs at lists.__openstack.org >>> >>> <mailto:Openstack-docs at lists.openstack.org> >>> >>> <mailto:Openstack-docs at lists.__openstack.org >>> >>> <mailto:Openstack-docs at lists.openstack.org>>> >>> >>> >>> >>> Subject: Re: [Openstack-docs] convert the HA guide from >>> >>> AsciiDoc to DocBook >>> >>> >>> >>> I'd be happy to do the conversion; it's something I'm >>> >>> familiar with, I >>> >>> have blocks of time where I can do it, and Diane, you can >>> >>>be >>> >>> more useful >>> >>> doing stuff that I can't, as a rule. >>> >>> >>> >>> That said, if you're set on doing it yourself, I won't >>> stop >>> >>> you. :) >>> >>> >>> >>> Let me know. >>> >>> >>> >>> ---- Nick >>> >>> >>> >>> >>> >>> On Wed, May 21, 2014 at 9:52 AM, Diane Fleming >>> >>> <diane.fleming at rackspace.com >>> >>> <mailto:diane.fleming at rackspace.com> >>> >>> <mailto:diane.fleming at __rackspace.com >>> >>> <mailto:diane.fleming at rackspace.com>>> wrote: >>> >>> >>> >>> Yes please! I'm happy to convert it if everyone >>> >>>agrees. >>> >>> >>> >>> >>> >>> /Diane/ >>> >>> /-----------------------------__-----------------/ >>> >>> >>> >>> Diane Fleming >>> >>> Software Developer II - US >>> >>> diane.fleming at rackspace.com >>> >>> <mailto:diane.fleming at rackspace.com> >>> >>> <mailto:diane.fleming at __rackspace.com >>> >>> <mailto:diane.fleming at rackspace.com>> >>> >>> Cell 512.323.6799 <tel:512.323.6799> <tel: >>> 512.323.6799 >>> >>> <tel:512.323.6799>> >>> >>> Office 512.874.1260 <tel:512.874.1260> >>> >>> <tel:512.874.1260 <tel:512.874.1260>> >>> >>> Skype drfleming0227 >>> >>> Google-plus diane.fleming at gmail.com >>> >>> <mailto:diane.fleming at gmail.com> >>> >>> <mailto:diane.fleming at gmail.__com >>> >>> <mailto:diane.fleming at gmail.com>> >>> >>> >>> >>> From: Anne Gentle <anne at openstack.org >>> >>> <mailto:anne at openstack.org> <mailto:anne at openstack.org >>> >>> <mailto:anne at openstack.org>>> >>> >>> >>> >>> Date: Wednesday, May 21, 2014 8:48 AM >>> >>> To: Christian Berendt <berendt at b1-systems.de >>> >>> <mailto:berendt at b1-systems.de> >>> >>> <mailto:berendt at b1-systems.de >>> >>> <mailto:berendt at b1-systems.de>>__> >>> >>> Cc: "openstack-docs at lists.__openstack.org >>> >>> <mailto:openstack-docs at lists.openstack.org> >>> >>> <mailto:openstack-docs at lists.__openstack.org >>> >>> <mailto:openstack-docs at lists.openstack.org>>" >>> >>> <Openstack-docs at lists.__openstack.org >>> >>> <mailto:Openstack-docs at lists.openstack.org> >>> >>> <mailto:Openstack-docs at lists.__openstack.org >>> >>> <mailto:Openstack-docs at lists.openstack.org>>> >>> >>> >>> >>> Subject: Re: [Openstack-docs] convert the HA guide >>> >>>from >>> >>> AsciiDoc to >>> >>> DocBook >>> >>> >>> >>> Glad you brought it up again. Last time someone >>> asked >>> >>>a >>> >>> year ago, >>> >>> here's how it went: >>> >>> >>> >>> >>> >>> >>> >>> >>> http://lists.openstack.org/__pipermail/openstack-docs/2013-__May/001630. >>> >>>html >>> >>> >>> >>> >>> >>> >>> >>>< >>> http://lists.openstack.org/pipermail/openstack-docs/2013-May/001630.htm >>> >>>l> >>> >>> >>> >>> >>> >>> Seems like a recurring theme. Let's see what happens >>> >>> this time around. >>> >>> >>> >>> Anne >>> >>> >>> >>> >>> >>> On Wed, May 21, 2014 at 8:41 AM, Christian Berendt >>> >>> <berendt at b1-systems.de <mailto: >>> berendt at b1-systems.de> >>> >>> <mailto:berendt at b1-systems.de >>> >>> <mailto:berendt at b1-systems.de>>__> wrote: >>> >>> >>> >>> Even I like AsciiDoc I would suggest to convert >>> >>>the >>> >>> HA guide from >>> >>> AsciiDoc to DocBook. All other guides are >>> written >>> >>> in DocBox and >>> >>> I don't >>> >>> see any benefit of keeping the HA guide in >>> >>> AsciiDoc. >>> >>> >>> >>> Christian. >>> >>> >>> >>> -- >>> >>> Christian Berendt >>> >>> Cloud Computing Solution Architect >>> >>> Mail: berendt at b1-systems.de >>> >>> <mailto:berendt at b1-systems.de> >>> >>><mailto:berendt at b1-systems.de >>> >>> <mailto:berendt at b1-systems.de>> >>> >>> >>> >>> >>> >>> B1 Systems GmbH >>> >>> Osterfeldstra?e 7 / 85088 Vohburg / >>> >>> http://www.b1-systems.de >>> >>> GF: Ralph Dehner / Unternehmenssitz: Vohburg / >>> AG: >>> >>> Ingolstadt,HRB 3537 >>> >>> >>> >>> >>> _________________________________________________ >>> >>> Openstack-docs mailing list >>> >>> Openstack-docs at lists.__openstack.org >>> >>> <mailto:Openstack-docs at lists.openstack.org> >>> >>> <mailto:Openstack-docs at lists.__openstack.org >>> >>> <mailto:Openstack-docs at lists.openstack.org>> >>> >>> >>> >>> >>> >>> >>> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs >>> >>> >>> >>> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> >>> >>> >>> >>> >>> >>> >>> >>> _________________________________________________ >>> >>> Openstack-docs mailing list >>> >>> Openstack-docs at lists.__openstack.org >>> >>> <mailto:Openstack-docs at lists.openstack.org> >>> >>> <mailto:Openstack-docs at lists.__openstack.org >>> >>> <mailto:Openstack-docs at lists.openstack.org>> >>> >>> >>> >>> >>> http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs >>> >>> >>> >>> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> _______________________________________________ >>> >>> Openstack-docs mailing list >>> >>> Openstack-docs at lists.openstack.org >>> >>> <mailto:Openstack-docs at lists.openstack.org> >>> >>> >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>> >>> >>> >>> >>> >> >>> >> _______________________________________________ >>> >> Openstack-docs mailing list >>> >> Openstack-docs at lists.openstack.org >>> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>> > >>> >>> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140525/f44f29f1/attachment-0001.html> From mkassawara at gmail.com Sun May 25 16:09:06 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Sun, 25 May 2014 10:09:06 -0600 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CABA+jQpmcQskEtNC7K2+FO0ubY-VqAHC=e6L-R-bSpVtQyEkWg@mail.gmail.com> References: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> <1168D4D0-7E00-4496-A6DA-BC1F409C6468@RACKSPACE.COM> <CABA+jQozp30xFbAMU24abS9J5MVWBK3Crm62qTedAhAOFVXFiw@mail.gmail.com> <8AA6205D-A359-4827-81D0-2993E00700F5@RACKSPACE.COM> <CABA+jQpmcQskEtNC7K2+FO0ubY-VqAHC=e6L-R-bSpVtQyEkWg@mail.gmail.com> Message-ID: <CABA+jQrg_YwCcP5DS4yhuozFn-G_Za0LeNTjZACeqS6B++65Dw@mail.gmail.com> Whoops, I noticed this discussion went off-list. On Sat, May 24, 2014 at 8:44 PM, Matt Kassawara <mkassawara at gmail.com>wrote: > I can't find any requirements for IDs outside of sections. For > consistency, I think we should require IDs on figures and tables too. > > P.S. - I just noticed that our thread went off-list. Should I put it back? > > > On Sat, May 24, 2014 at 7:47 PM, Diane Fleming < > diane.fleming at rackspace.com> wrote: > >> Yes, sections are not named consistently. Are id's required on figures >> and tables? Or only if you cross-ref them? (I don't remember.) >> >> Sent from my iPhone >> >> On May 24, 2014, at 11:15 AM, "Matt Kassawara" <mkassawara at gmail.com> >> wrote: >> >> Thanks! I took a look and mostly found consistency with bk_* and ch_*, >> but sections often lack section_*. Many figures and tables often lack IDs. >> >> >> On Sat, May 24, 2014 at 9:33 AM, Diane Fleming < >> diane.fleming at rackspace.com> wrote: >> >>> Matt, look at openstack-manuals -> user-guide, config ref, common, or >>> the admin guide - i think all those use a consistent naming style. Chapters >>> ch_*, sections section_*, books bk_*. I do not remember what we used for >>> images and tables - but look there for existing conventions. >>> >>> Sent from my iPhone >>> >>> On May 24, 2014, at 9:46 AM, "Matt Kassawara" <mkassawara at gmail.com> >>> wrote: >>> >>> Would consistently indicating type within an ID help clarify >>> references? For example, chapter IDs always start with "ch_", section IDs >>> always start with "sec_", figure IDs start with "fig_", etc. >>> >>> >>> On Thu, May 22, 2014 at 5:58 PM, Matt Kassawara <mkassawara at gmail.com>wrote: >>> >>>> I found some inconsistencies with filenames and chapter/section IDs >>>> while auditing the Installation Guide. I thought I found some conventions >>>> while updating the guide for Icehouse, but can't find them now. If they >>>> exist, can someone point me to them? If not, we should develop some so we >>>> can proceed with the improvements. >>>> >>> >>> _______________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.openstack.org >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>> >>> >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140525/7ec61349/attachment.html> From aj at suse.com Sun May 25 19:50:27 2014 From: aj at suse.com (Andreas Jaeger) Date: Sun, 25 May 2014 21:50:27 +0200 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> References: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> Message-ID: <53824983.3060301@suse.com> On 05/24/2014 04:45 PM, Matt Kassawara wrote: > Would consistently indicating type within an ID help clarify references? > For example, chapter IDs always start with "ch_", section IDs always > start with "sec_", figure IDs start with "fig_", etc. Yeah, that would help. When I add xml:ids, I normally use sec_FILENAME for the first section and sec_FILENAME_TITLE for any additional sections. FILENAME is either the filename or the first title. I don't think we should remain now everything - but we should have a rule for new files and new xml:ids moving forward. Remaining has the problem that it creates new URLs and the old ones stay. Once that issue is fixed, we can rename more easily, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Sun May 25 19:55:17 2014 From: aj at suse.com (Andreas Jaeger) Date: Sun, 25 May 2014 21:55:17 +0200 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> Message-ID: <53824AA5.8020702@suse.com> On 05/25/2014 07:51 AM, Nick Chase wrote: > Great. Done. > https://blueprints.launchpad.net/openstack-manuals/+spec/convert-ha-guide-to-docbook > > Joseph, do you know when you'll be done with the list fixes? I don't > know how to make that numbered list work right in ASCIIDoc, but I do > know how to make it work in Docbook, so we could also, if there's > agreement here, accept the patch as it is and I'll incorporate it and > fix it immediately in the Docbook. I'm fine with accepting the patch if you get this done quickly. Feel free to ignore my -1 - but I'm not removing it to give others the chance to chime in, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From nchase at mirantis.com Sun May 25 20:05:43 2014 From: nchase at mirantis.com (Nick Chase) Date: Sun, 25 May 2014 16:05:43 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <53824AA5.8020702@suse.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> <53824AA5.8020702@suse.com> Message-ID: <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> I can do it immediately. I was planning to work on this this afternoon so that would be perfect. ---- Nick On May 25, 2014 3:55 PM, "Andreas Jaeger" <aj at suse.com> wrote: > On 05/25/2014 07:51 AM, Nick Chase wrote: > > Great. Done. > > > https://blueprints.launchpad.net/openstack-manuals/+spec/convert-ha-guide-to-docbook > > > > Joseph, do you know when you'll be done with the list fixes? I don't > > know how to make that numbered list work right in ASCIIDoc, but I do > > know how to make it work in Docbook, so we could also, if there's > > agreement here, accept the patch as it is and I'll incorporate it and > > fix it immediately in the Docbook. > > I'm fine with accepting the patch if you get this done quickly. Feel > free to ignore my -1 - but I'm not removing it to give others the chance > to chime in, > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140525/406c97ba/attachment.html> From anne at openstack.org Sun May 25 21:32:25 2014 From: anne at openstack.org (Anne Gentle) Date: Sun, 25 May 2014 16:32:25 -0500 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <53824983.3060301@suse.com> References: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> <53824983.3060301@suse.com> Message-ID: <CAD0KtVFPYs7LdCYUunnD5Yk1qvoCAcoUvjgkVDbW2YyuNSU0Xg@mail.gmail.com> Something to think about for ch and sec is that we won't always author in a book-like manner, so let's not lock ourselves into that sort of thinking due to current file names. Stick to the install guide for now, to apply conventions, just please don't use something as meaningful semantically as chapter and section. Anne On Sun, May 25, 2014 at 2:50 PM, Andreas Jaeger <aj at suse.com> wrote: > On 05/24/2014 04:45 PM, Matt Kassawara wrote: > > Would consistently indicating type within an ID help clarify references? > > For example, chapter IDs always start with "ch_", section IDs always > > start with "sec_", figure IDs start with "fig_", etc. > > > Yeah, that would help. > > When I add xml:ids, I normally use sec_FILENAME for the first section > and sec_FILENAME_TITLE for any additional sections. FILENAME is either > the filename or the first title. > > I don't think we should remain now everything - but we should have a > rule for new files and new xml:ids moving forward. Remaining has the > problem that it creates new URLs and the old ones stay. Once that issue > is fixed, we can rename more easily, > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140525/88666b3d/attachment.html> From sgordon at redhat.com Sun May 25 21:50:41 2014 From: sgordon at redhat.com (Steve Gordon) Date: Sun, 25 May 2014 17:50:41 -0400 (EDT) Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CAD0KtVFPYs7LdCYUunnD5Yk1qvoCAcoUvjgkVDbW2YyuNSU0Xg@mail.gmail.com> References: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> <53824983.3060301@suse.com> <CAD0KtVFPYs7LdCYUunnD5Yk1qvoCAcoUvjgkVDbW2YyuNSU0Xg@mail.gmail.com> Message-ID: <1965553805.18459527.1401054641947.JavaMail.zimbra@redhat.com> ----- Original Message ----- > From: "Anne Gentle" <anne at openstack.org> > To: "Andreas Jaeger" <aj at suse.com> > > Something to think about for ch and sec is that we won't always author in a > book-like manner, so let's not lock ourselves into that sort of thinking > due to current file names. > > Stick to the install guide for now, to apply conventions, just please don't > use something as meaningful semantically as chapter and section. I actually think it's important/useful information in the filename. It reflects the root node of the file's XML which has an impact on where you can nest/include it in another document (you can't include a chapter in a section for example, but you can include a section in a chapter). It's got more to do with the realities of the format being used than whether we're thinking in terms of books, articles, etc. Granted if we moved to a non-XML format this would no longer be the case, but I think we'd have bigger conversion issues than bulk renaming the files/links. ;) -Steve From anne at openstack.org Sun May 25 23:27:26 2014 From: anne at openstack.org (Anne Gentle) Date: Sun, 25 May 2014 18:27:26 -0500 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <1965553805.18459527.1401054641947.JavaMail.zimbra@redhat.com> References: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> <53824983.3060301@suse.com> <CAD0KtVFPYs7LdCYUunnD5Yk1qvoCAcoUvjgkVDbW2YyuNSU0Xg@mail.gmail.com> <1965553805.18459527.1401054641947.JavaMail.zimbra@redhat.com> Message-ID: <CAD0KtVEGJ0jrFCMFh5nXOBee6ZbRCeE90GeLmXZ_8XZRGj9Qpw@mail.gmail.com> On Sun, May 25, 2014 at 4:50 PM, Steve Gordon <sgordon at redhat.com> wrote: > ----- Original Message ----- > > From: "Anne Gentle" <anne at openstack.org> > > To: "Andreas Jaeger" <aj at suse.com> > > > > Something to think about for ch and sec is that we won't always author > in a > > book-like manner, so let's not lock ourselves into that sort of thinking > > due to current file names. > > > > Stick to the install guide for now, to apply conventions, just please > don't > > use something as meaningful semantically as chapter and section. > > I actually think it's important/useful information in the filename. It > reflects the root node of the file's XML which has an impact on where you > can nest/include it in another document (you can't include a chapter in a > section for example, but you can include a section in a chapter). It's got > more to do with the realities of the format being used than whether we're > thinking in terms of books, articles, etc. > I agree it's a useful codification in the file name, but I don't think we want it in the xml:id. The xml:id is used for SEO, for human-readable URLs, and so on. Let's not leak our abstraction further than we have to. :) Anne > > Granted if we moved to a non-XML format this would no longer be the case, > but I think we'd have bigger conversion issues than bulk renaming the > files/links. ;) > > -Steve > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140525/0ccc83f4/attachment.html> From joseph.robinson at RACKSPACE.COM Sun May 25 23:47:35 2014 From: joseph.robinson at RACKSPACE.COM (Joseph Robinson) Date: Sun, 25 May 2014 23:47:35 +0000 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> <53824AA5.8020702@suse.com> <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> Message-ID: <CFA8BF47.13C7%joseph.robinson@rackspace.com> Yes, that?s a great idea, and I agree. Apologies for the delay. It will be great to have the procedure built with xml. It will take more time to find out why it is not building the procedure correctly in Ascii then it would to merge the changes and immediately rebuild with xml. Proceed when ready. -Joe From: Nick Chase <nchase at mirantis.com<mailto:nchase at mirantis.com>> Date: Monday, 26 May 2014 6:05 am To: aj <aj at suse.com<mailto:aj at suse.com>> Cc: "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>> Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook I can do it immediately. I was planning to work on this this afternoon so that would be perfect. ---- Nick On May 25, 2014 3:55 PM, "Andreas Jaeger" <aj at suse.com<mailto:aj at suse.com>> wrote: On 05/25/2014 07:51 AM, Nick Chase wrote: > Great. Done. > https://blueprints.launchpad.net/openstack-manuals/+spec/convert-ha-guide-to-docbook > > Joseph, do you know when you'll be done with the list fixes? I don't > know how to make that numbered list work right in ASCIIDoc, but I do > know how to make it work in Docbook, so we could also, if there's > agreement here, accept the patch as it is and I'll incorporate it and > fix it immediately in the Docbook. I'm fine with accepting the patch if you get this done quickly. Feel free to ignore my -1 - but I'm not removing it to give others the chance to chime in, Andreas -- Andreas Jaeger aj@{suse.com<http://suse.com>,opensuse.org<http://opensuse.org>} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140525/80144c06/attachment.html> From diane.fleming at RACKSPACE.COM Sun May 25 23:59:00 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Sun, 25 May 2014 23:59:00 +0000 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CAD0KtVEGJ0jrFCMFh5nXOBee6ZbRCeE90GeLmXZ_8XZRGj9Qpw@mail.gmail.com> References: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> <53824983.3060301@suse.com> <CAD0KtVFPYs7LdCYUunnD5Yk1qvoCAcoUvjgkVDbW2YyuNSU0Xg@mail.gmail.com> <1965553805.18459527.1401054641947.JavaMail.zimbra@redhat.com>, <CAD0KtVEGJ0jrFCMFh5nXOBee6ZbRCeE90GeLmXZ_8XZRGj9Qpw@mail.gmail.com> Message-ID: <35069176-7827-4378-AB54-C252732D58EB@RACKSPACE.COM> +1 for file name conventions -1 for xml:id conventions Sent from my iPhone On May 25, 2014, at 6:28 PM, "Anne Gentle" <anne at openstack.org<mailto:anne at openstack.org>> wrote: On Sun, May 25, 2014 at 4:50 PM, Steve Gordon <sgordon at redhat.com<mailto:sgordon at redhat.com>> wrote: ----- Original Message ----- > From: "Anne Gentle" <anne at openstack.org<mailto:anne at openstack.org>> > To: "Andreas Jaeger" <aj at suse.com<mailto:aj at suse.com>> > > Something to think about for ch and sec is that we won't always author in a > book-like manner, so let's not lock ourselves into that sort of thinking > due to current file names. > > Stick to the install guide for now, to apply conventions, just please don't > use something as meaningful semantically as chapter and section. I actually think it's important/useful information in the filename. It reflects the root node of the file's XML which has an impact on where you can nest/include it in another document (you can't include a chapter in a section for example, but you can include a section in a chapter). It's got more to do with the realities of the format being used than whether we're thinking in terms of books, articles, etc. I agree it's a useful codification in the file name, but I don't think we want it in the xml:id. The xml:id is used for SEO, for human-readable URLs, and so on. Let's not leak our abstraction further than we have to. :) Anne Granted if we moved to a non-XML format this would no longer be the case, but I think we'd have bigger conversion issues than bulk renaming the files/links. ;) -Steve _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140525/32c8f332/attachment.html> From nchase at mirantis.com Mon May 26 05:44:20 2014 From: nchase at mirantis.com (Nick Chase) Date: Mon, 26 May 2014 01:44:20 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CFA8BF47.13C7%joseph.robinson@rackspace.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> <53824AA5.8020702@suse.com> <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> <CFA8BF47.13C7%joseph.robinson@rackspace.com> Message-ID: <CA+p99Gn3cBBKW1cXX1seXuoUfd7Ahn9vNLw=nL734T_kABwmpA@mail.gmail.com> OK, so here's where we are: I've got one patch in that does the wholesale conversion to XML, but doesn't have things broken down and audited yet. That's here: https://review.openstack.org/#/c/95401/ However, as you can see, it doesn't pass tox. It doesn't pass tox locally because it's trying to convert it to docbook, and there's nothing to convert. I've removed that functionality from os-docs-tools here: https://review.openstack.org/#/c/95406/ But that needs to be merged before I can run tox on the book to look for other problems. I think. Anyway, I've just commented code here; I'm happy to actually delete it if I've done the right thing, but I didn't want to just hack out a bunch of code without someone more familiar looking at it first. Thanks! ---- Nick On Sun, May 25, 2014 at 7:47 PM, Joseph Robinson < joseph.robinson at rackspace.com> wrote: > Yes, that?s a great idea, and I agree. Apologies for the delay. It will > be great to have the procedure built with xml. > > It will take more time to find out why it is not building the procedure > correctly in Ascii then it would to merge the changes and immediately > rebuild with xml. > > Proceed when ready. > > -Joe > > From: Nick Chase <nchase at mirantis.com> > Date: Monday, 26 May 2014 6:05 am > To: aj <aj at suse.com> > Cc: "openstack-docs at lists.openstack.org" < > openstack-docs at lists.openstack.org> > > Subject: Re: [Openstack-docs] convert the HA guide from AsciiDoc to > DocBook > > I can do it immediately. I was planning to work on this this afternoon > so that would be perfect. > > ---- Nick > On May 25, 2014 3:55 PM, "Andreas Jaeger" <aj at suse.com> wrote: > >> On 05/25/2014 07:51 AM, Nick Chase wrote: >> > Great. Done. >> > >> https://blueprints.launchpad.net/openstack-manuals/+spec/convert-ha-guide-to-docbook >> > >> > Joseph, do you know when you'll be done with the list fixes? I don't >> > know how to make that numbered list work right in ASCIIDoc, but I do >> > know how to make it work in Docbook, so we could also, if there's >> > agreement here, accept the patch as it is and I'll incorporate it and >> > fix it immediately in the Docbook. >> >> I'm fine with accepting the patch if you get this done quickly. Feel >> free to ignore my -1 - but I'm not removing it to give others the chance >> to chime in, >> >> Andreas >> -- >> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany >> GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/8e486515/attachment-0001.html> From aj at suse.com Mon May 26 06:24:04 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 26 May 2014 08:24:04 +0200 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> <53824AA5.8020702@suse.com> <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> Message-ID: <5382DE04.70900@suse.com> Thanks Nick for the conversion! So, to get this in, we need to do the following: 1) We need a new release of openstack-doc-tools with this patch in: https://review.openstack.org/#/c/95406/ 2) Approve Nick's patch https://review.openstack.org/#/c/95401/ 3) Update infra-job (I'll ping them once 2 is in): https://review.openstack.org/#/c/95414/ Reviews of patches are welcome, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Mon May 26 06:25:53 2014 From: aj at suse.com (Andreas Jaeger) Date: Mon, 26 May 2014 08:25:53 +0200 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CA+p99Gn3cBBKW1cXX1seXuoUfd7Ahn9vNLw=nL734T_kABwmpA@mail.gmail.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> <53824AA5.8020702@suse.com> <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> <CFA8BF47.13C7%joseph.robinson@rackspace.com> <CA+p99Gn3cBBKW1cXX1seXuoUfd7Ahn9vNLw=nL734T_kABwmpA@mail.gmail.com> Message-ID: <5382DE71.2080908@suse.com> On 05/26/2014 07:44 AM, Nick Chase wrote: > OK, so here's where we are: > > I've got one patch in that does the wholesale conversion to XML, but > doesn't have things broken down and audited yet. That's here: > > https://review.openstack.org/#/c/95401/ > > However, as you can see, it doesn't pass tox. It doesn't pass tox > locally because it's trying to convert it to docbook, and there's > nothing to convert. I've removed that functionality from os-docs-tools > here: > > https://review.openstack.org/#/c/95406/ > > But that needs to be merged before I can run tox on the book to look for > other problems. I think. Agreed. I should have read my whole INBOX before patching and answering ;) > Anyway, I've just commented code here; I'm happy to actually delete it > if I've done the right thing, but I didn't want to just hack out a bunch > of code without someone more familiar looking at it first. You commented out too much in that file and missed the parts that actually builds the books, I've updated your patch. Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From joseph.robinson at RACKSPACE.COM Mon May 26 07:41:49 2014 From: joseph.robinson at RACKSPACE.COM (Joseph Robinson) Date: Mon, 26 May 2014 07:41:49 +0000 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <5382DE71.2080908@suse.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> <53824AA5.8020702@suse.com> <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> <CFA8BF47.13C7%joseph.robinson@rackspace.com> <CA+p99Gn3cBBKW1cXX1seXuoUfd7Ahn9vNLw=nL734T_kABwmpA@mail.gmail.com> <5382DE71.2080908@suse.com> Message-ID: <CFA92DCF.13E2%joseph.robinson@rackspace.com> I rewrote the edits to the HA guide with explicit instead of implicit numbering, and sorry it took so long to research and apply this AsciiDoc list type. The patch is ready to go for the conversion now. ?Joe On 26/05/2014 4:25 pm, "Andreas Jaeger" <aj at suse.com> wrote: >On 05/26/2014 07:44 AM, Nick Chase wrote: >> OK, so here's where we are: >> >> I've got one patch in that does the wholesale conversion to XML, but >> doesn't have things broken down and audited yet. That's here: >> >> https://review.openstack.org/#/c/95401/ >> >> However, as you can see, it doesn't pass tox. It doesn't pass tox >> locally because it's trying to convert it to docbook, and there's >> nothing to convert. I've removed that functionality from os-docs-tools >> here: >> >> https://review.openstack.org/#/c/95406/ >> >> But that needs to be merged before I can run tox on the book to look for >> other problems. I think. > >Agreed. I should have read my whole INBOX before patching and answering ;) > >> Anyway, I've just commented code here; I'm happy to actually delete it >> if I've done the right thing, but I didn't want to just hack out a bunch >> of code without someone more familiar looking at it first. > >You commented out too much in that file and missed the parts that >actually builds the books, I've updated your patch. > >Andreas >-- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From nchase at mirantis.com Mon May 26 14:32:23 2014 From: nchase at mirantis.com (Nick Chase) Date: Mon, 26 May 2014 10:32:23 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CFA92DCF.13E2%joseph.robinson@rackspace.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> <53824AA5.8020702@suse.com> <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> <CFA8BF47.13C7%joseph.robinson@rackspace.com> <CA+p99Gn3cBBKW1cXX1seXuoUfd7Ahn9vNLw=nL734T_kABwmpA@mail.gmail.com> <5382DE71.2080908@suse.com> <CFA92DCF.13E2%joseph.robinson@rackspace.com> Message-ID: <CA+p99Gn5KUSeinY8nR-=hc=6NPBqtqYjHu=3Lvbk00dXJwtA1A@mail.gmail.com> I actually fixed it in the XML version so it's ok. On May 26, 2014 3:41 AM, "Joseph Robinson" <joseph.robinson at rackspace.com> wrote: > I rewrote the edits to the HA guide with explicit instead of implicit > numbering, and sorry it took so long to research and apply this AsciiDoc > list type. The patch is ready to go for the conversion now. > > ?Joe > > On 26/05/2014 4:25 pm, "Andreas Jaeger" <aj at suse.com> wrote: > > >On 05/26/2014 07:44 AM, Nick Chase wrote: > >> OK, so here's where we are: > >> > >> I've got one patch in that does the wholesale conversion to XML, but > >> doesn't have things broken down and audited yet. That's here: > >> > >> https://review.openstack.org/#/c/95401/ > >> > >> However, as you can see, it doesn't pass tox. It doesn't pass tox > >> locally because it's trying to convert it to docbook, and there's > >> nothing to convert. I've removed that functionality from os-docs-tools > >> here: > >> > >> https://review.openstack.org/#/c/95406/ > >> > >> But that needs to be merged before I can run tox on the book to look for > >> other problems. I think. > > > >Agreed. I should have read my whole INBOX before patching and answering ;) > > > >> Anyway, I've just commented code here; I'm happy to actually delete it > >> if I've done the right thing, but I didn't want to just hack out a bunch > >> of code without someone more familiar looking at it first. > > > >You commented out too much in that file and missed the parts that > >actually builds the books, I've updated your patch. > > > >Andreas > >-- > > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/42889aed/attachment.html> From nchase at mirantis.com Mon May 26 14:35:43 2014 From: nchase at mirantis.com (Nick Chase) Date: Mon, 26 May 2014 10:35:43 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CA+p99Gn5KUSeinY8nR-=hc=6NPBqtqYjHu=3Lvbk00dXJwtA1A@mail.gmail.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> <53824AA5.8020702@suse.com> <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> <CFA8BF47.13C7%joseph.robinson@rackspace.com> <CA+p99Gn3cBBKW1cXX1seXuoUfd7Ahn9vNLw=nL734T_kABwmpA@mail.gmail.com> <5382DE71.2080908@suse.com> <CFA92DCF.13E2%joseph.robinson@rackspace.com> <CA+p99Gn5KUSeinY8nR-=hc=6NPBqtqYjHu=3Lvbk00dXJwtA1A@mail.gmail.com> Message-ID: <CA+p99GkvhLf3VBrXT_2h=2R6rgLt+jced2zTec-aGFwb0tC2OQ@mail.gmail.com> I should be clear. Before I did the conversion, I applied your patch. I then did the conversion and fixed the list so that it renders properly. ---- Nick On May 26, 2014 10:32 AM, "Nick Chase" <nchase at mirantis.com> wrote: > I actually fixed it in the XML version so it's ok. > On May 26, 2014 3:41 AM, "Joseph Robinson" <joseph.robinson at rackspace.com> > wrote: > >> I rewrote the edits to the HA guide with explicit instead of implicit >> numbering, and sorry it took so long to research and apply this AsciiDoc >> list type. The patch is ready to go for the conversion now. >> >> ?Joe >> >> On 26/05/2014 4:25 pm, "Andreas Jaeger" <aj at suse.com> wrote: >> >> >On 05/26/2014 07:44 AM, Nick Chase wrote: >> >> OK, so here's where we are: >> >> >> >> I've got one patch in that does the wholesale conversion to XML, but >> >> doesn't have things broken down and audited yet. That's here: >> >> >> >> https://review.openstack.org/#/c/95401/ >> >> >> >> However, as you can see, it doesn't pass tox. It doesn't pass tox >> >> locally because it's trying to convert it to docbook, and there's >> >> nothing to convert. I've removed that functionality from os-docs-tools >> >> here: >> >> >> >> https://review.openstack.org/#/c/95406/ >> >> >> >> But that needs to be merged before I can run tox on the book to look >> for >> >> other problems. I think. >> > >> >Agreed. I should have read my whole INBOX before patching and answering >> ;) >> > >> >> Anyway, I've just commented code here; I'm happy to actually delete it >> >> if I've done the right thing, but I didn't want to just hack out a >> bunch >> >> of code without someone more familiar looking at it first. >> > >> >You commented out too much in that file and missed the parts that >> >actually builds the books, I've updated your patch. >> > >> >Andreas >> >-- >> > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi >> > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany >> > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) >> > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 >> >> -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/486310d5/attachment.html> From nchase at mirantis.com Mon May 26 14:39:39 2014 From: nchase at mirantis.com (Nick Chase) Date: Mon, 26 May 2014 10:39:39 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <5382DE71.2080908@suse.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> <53824AA5.8020702@suse.com> <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> <CFA8BF47.13C7%joseph.robinson@rackspace.com> <CA+p99Gn3cBBKW1cXX1seXuoUfd7Ahn9vNLw=nL734T_kABwmpA@mail.gmail.com> <5382DE71.2080908@suse.com> Message-ID: <CA+p99GnrsU07jj7j+=bb7B0=k8_rPDnN2fQmNdN_WDC=D14jhg@mail.gmail.com> On May 26, 2014 2:25 AM, "Andreas Jaeger" <aj at suse.com> wrote: > > On 05/26/2014 07:44 AM, Nick Chase wrote: > > OK, so here's where we are: > > > > I've got one patch in that does the wholesale conversion to XML, but > > doesn't have things broken down and audited yet. That's here: > > > > https://review.openstack.org/#/c/95401/ > > > > However, as you can see, it doesn't pass tox. It doesn't pass tox > > locally because it's trying to convert it to docbook, and there's > > nothing to convert. I've removed that functionality from os-docs-tools > > here: > > > > https://review.openstack.org/#/c/95406/ > > > > But that needs to be merged before I can run tox on the book to look for > > other problems. I think. > > Agreed. I should have read my whole INBOX before patching and answering ;) If you're like me you'd never get anything done that way. :) > > Anyway, I've just commented code here; I'm happy to actually delete it > > if I've done the right thing, but I didn't want to just hack out a bunch > > of code without someone more familiar looking at it first. > > You commented out too much in that file and missed the parts that > actually builds the books, I've updated your patch. And that's why I commented instead of deleting. :) Thanks for the assist. Anyway I've got the next one, which breaks it all down to the section level, just about ready to go. Then i can do cleanup. ---- Nick -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/c88e2929/attachment.html> From mkassawara at gmail.com Mon May 26 14:42:53 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Mon, 26 May 2014 08:42:53 -0600 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <35069176-7827-4378-AB54-C252732D58EB@RACKSPACE.COM> References: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> <53824983.3060301@suse.com> <CAD0KtVFPYs7LdCYUunnD5Yk1qvoCAcoUvjgkVDbW2YyuNSU0Xg@mail.gmail.com> <1965553805.18459527.1401054641947.JavaMail.zimbra@redhat.com> <CAD0KtVEGJ0jrFCMFh5nXOBee6ZbRCeE90GeLmXZ_8XZRGj9Qpw@mail.gmail.com> <35069176-7827-4378-AB54-C252732D58EB@RACKSPACE.COM> Message-ID: <CABA+jQoKAoy8OUtNNf1bwUK3jCRrYqGRx22NpH_eUuATgD0fig@mail.gmail.com> How about describing the hierarchy in IDs, but not necessarily with ch_, section_, etc? For example: ch_networking -> networking section_neutron-networking-ml2 -> networking-neutron-ml2 section_neutron-ml2-controller-node -> networking-neutron-ml2-controller-node Also, would it help to indicate type in figure, table, and similar element IDs? For example: example-architecture-with-legacy-networking -> fig_example-architecture-with-legacy-networking table1 -> tab_getstart-openstack-services (from common/ch_getstart.xml) para3 -> par_getstart-3 (from common/ch_getstart.xml) Or... am I still the totally crazy noob? P.S. - I'm also interested in ideas for standardizing filenames and/or locations for figures. On Sun, May 25, 2014 at 5:59 PM, Diane Fleming <diane.fleming at rackspace.com>wrote: > +1 for file name conventions > -1 for xml:id conventions > > > > Sent from my iPhone > > On May 25, 2014, at 6:28 PM, "Anne Gentle" <anne at openstack.org> wrote: > > > > > On Sun, May 25, 2014 at 4:50 PM, Steve Gordon <sgordon at redhat.com> wrote: > >> ----- Original Message ----- >> > From: "Anne Gentle" <anne at openstack.org> >> > To: "Andreas Jaeger" <aj at suse.com> >> > >> > Something to think about for ch and sec is that we won't always author >> in a >> > book-like manner, so let's not lock ourselves into that sort of thinking >> > due to current file names. >> > >> > Stick to the install guide for now, to apply conventions, just please >> don't >> > use something as meaningful semantically as chapter and section. >> >> I actually think it's important/useful information in the filename. It >> reflects the root node of the file's XML which has an impact on where you >> can nest/include it in another document (you can't include a chapter in a >> section for example, but you can include a section in a chapter). It's got >> more to do with the realities of the format being used than whether we're >> thinking in terms of books, articles, etc. >> > > I agree it's a useful codification in the file name, but I don't think > we want it in the xml:id. The xml:id is used for SEO, for human-readable > URLs, and so on. Let's not leak our abstraction further than we have to. :) > Anne > > >> >> Granted if we moved to a non-XML format this would no longer be the case, >> but I think we'd have bigger conversion issues than bulk renaming the >> files/links. ;) >> >> -Steve >> > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/72fc62dd/attachment-0001.html> From diane.fleming at RACKSPACE.COM Mon May 26 14:47:42 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Mon, 26 May 2014 14:47:42 +0000 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CABA+jQoKAoy8OUtNNf1bwUK3jCRrYqGRx22NpH_eUuATgD0fig@mail.gmail.com> Message-ID: <CFA8BDF2.2DFA0%diane.fleming@rackspace.com> Matt, What problem are you trying to solve by updating the xml:id values? I'd start with one issue ? the file names ? and then figure out what you want to accomplish by changing xml:id values. I personally don't see much value-add with updates to the ID's, but I could be missing something! thanks, Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com From: Matt Kassawara <mkassawara at gmail.com<mailto:mkassawara at gmail.com>> Date: Monday, May 26, 2014 9:42 AM To: Diane Fleming <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>> Cc: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>>, Andreas Jaeger <aj at suse.com<mailto:aj at suse.com>>, "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>> Subject: Re: [Openstack-docs] Conventions for filenames and chapter/section IDs How about describing the hierarchy in IDs, but not necessarily with ch_, section_, etc? For example: ch_networking -> networking section_neutron-networking-ml2 -> networking-neutron-ml2 section_neutron-ml2-controller-node -> networking-neutron-ml2-controller-node Also, would it help to indicate type in figure, table, and similar element IDs? For example: example-architecture-with-legacy-networking -> fig_example-architecture-with-legacy-networking table1 -> tab_getstart-openstack-services (from common/ch_getstart.xml) para3 -> par_getstart-3 (from common/ch_getstart.xml) Or... am I still the totally crazy noob? P.S. - I'm also interested in ideas for standardizing filenames and/or locations for figures. On Sun, May 25, 2014 at 5:59 PM, Diane Fleming <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>> wrote: +1 for file name conventions -1 for xml:id conventions Sent from my iPhone On May 25, 2014, at 6:28 PM, "Anne Gentle" <anne at openstack.org<mailto:anne at openstack.org>> wrote: On Sun, May 25, 2014 at 4:50 PM, Steve Gordon <sgordon at redhat.com<mailto:sgordon at redhat.com>> wrote: ----- Original Message ----- > From: "Anne Gentle" <anne at openstack.org<mailto:anne at openstack.org>> > To: "Andreas Jaeger" <aj at suse.com<mailto:aj at suse.com>> > > Something to think about for ch and sec is that we won't always author in a > book-like manner, so let's not lock ourselves into that sort of thinking > due to current file names. > > Stick to the install guide for now, to apply conventions, just please don't > use something as meaningful semantically as chapter and section. I actually think it's important/useful information in the filename. It reflects the root node of the file's XML which has an impact on where you can nest/include it in another document (you can't include a chapter in a section for example, but you can include a section in a chapter). It's got more to do with the realities of the format being used than whether we're thinking in terms of books, articles, etc. I agree it's a useful codification in the file name, but I don't think we want it in the xml:id. The xml:id is used for SEO, for human-readable URLs, and so on. Let's not leak our abstraction further than we have to. :) Anne Granted if we moved to a non-XML format this would no longer be the case, but I think we'd have bigger conversion issues than bulk renaming the files/links. ;) -Steve _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/35a8d507/attachment.html> From nchase at mirantis.com Mon May 26 15:06:56 2014 From: nchase at mirantis.com (Nick Chase) Date: Mon, 26 May 2014 11:06:56 -0400 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CFA8BDF2.2DFA0%diane.fleming@rackspace.com> References: <CABA+jQoKAoy8OUtNNf1bwUK3jCRrYqGRx22NpH_eUuATgD0fig@mail.gmail.com> <CFA8BDF2.2DFA0%diane.fleming@rackspace.com> Message-ID: <CA+p99Gnwea4hT=bo4=W4sTOG4jVXjbi8VrgO8UmkmDx9c_WxuA@mail.gmail.com> Plus my concern in changing Id values is breaking any references. ---- Nick On May 26, 2014 10:49 AM, "Diane Fleming" <diane.fleming at rackspace.com> wrote: > Matt, > > What problem are you trying to solve by updating the xml:id values? > > I'd start with one issue ? the file names ? and then figure out what you > want to accomplish by changing xml:id values. > > I personally don't see much value-add with updates to the ID's, but I > could be missing something! > > thanks, > > *Diane* > *----------------------------------------------* > Diane Fleming > Software Developer II - US > diane.fleming at rackspace.com > Cell 512.323.6799 > Office 512.874.1260 > Skype drfleming0227 > Google-plus diane.fleming at gmail.com > > From: Matt Kassawara <mkassawara at gmail.com> > Date: Monday, May 26, 2014 9:42 AM > To: Diane Fleming <diane.fleming at rackspace.com> > Cc: Anne Gentle <anne at openstack.org>, Andreas Jaeger <aj at suse.com>, " > openstack-docs at lists.openstack.org" <openstack-docs at lists.openstack.org> > Subject: Re: [Openstack-docs] Conventions for filenames and > chapter/section IDs > > How about describing the hierarchy in IDs, but not necessarily with > ch_, section_, etc? For example: > > ch_networking -> networking > section_neutron-networking-ml2 -> networking-neutron-ml2 > section_neutron-ml2-controller-node -> > networking-neutron-ml2-controller-node > > Also, would it help to indicate type in figure, table, and similar > element IDs? For example: > > example-architecture-with-legacy-networking -> > fig_example-architecture-with-legacy-networking > table1 -> tab_getstart-openstack-services (from common/ch_getstart.xml) > para3 -> par_getstart-3 (from common/ch_getstart.xml) > > Or... am I still the totally crazy noob? > > P.S. - I'm also interested in ideas for standardizing filenames and/or > locations for figures. > > > On Sun, May 25, 2014 at 5:59 PM, Diane Fleming < > diane.fleming at rackspace.com> wrote: > >> +1 for file name conventions >> -1 for xml:id conventions >> >> >> >> Sent from my iPhone >> >> On May 25, 2014, at 6:28 PM, "Anne Gentle" <anne at openstack.org> wrote: >> >> >> >> >> On Sun, May 25, 2014 at 4:50 PM, Steve Gordon <sgordon at redhat.com> wrote: >> >>> ----- Original Message ----- >>> > From: "Anne Gentle" <anne at openstack.org> >>> > To: "Andreas Jaeger" <aj at suse.com> >>> > >>> > Something to think about for ch and sec is that we won't always author >>> in a >>> > book-like manner, so let's not lock ourselves into that sort of >>> thinking >>> > due to current file names. >>> > >>> > Stick to the install guide for now, to apply conventions, just please >>> don't >>> > use something as meaningful semantically as chapter and section. >>> >>> I actually think it's important/useful information in the filename. It >>> reflects the root node of the file's XML which has an impact on where you >>> can nest/include it in another document (you can't include a chapter in a >>> section for example, but you can include a section in a chapter). It's got >>> more to do with the realities of the format being used than whether we're >>> thinking in terms of books, articles, etc. >>> >> >> I agree it's a useful codification in the file name, but I don't think >> we want it in the xml:id. The xml:id is used for SEO, for human-readable >> URLs, and so on. Let's not leak our abstraction further than we have to. :) >> Anne >> >> >>> >>> Granted if we moved to a non-XML format this would no longer be the >>> case, but I think we'd have bigger conversion issues than bulk renaming the >>> files/links. ;) >>> >>> -Steve >>> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/df38de55/attachment-0001.html> From mkassawara at gmail.com Mon May 26 15:16:18 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Mon, 26 May 2014 09:16:18 -0600 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CFA8BDF2.2DFA0%diane.fleming@rackspace.com> References: <CABA+jQoKAoy8OUtNNf1bwUK3jCRrYqGRx22NpH_eUuATgD0fig@mail.gmail.com> <CFA8BDF2.2DFA0%diane.fleming@rackspace.com> Message-ID: <CABA+jQpEsfNWytP+yY2NGwt03rmNWPttQw-FaDbAG1YBozWuJA@mail.gmail.com> Oops... didn't reply-all the first time. IDs came up as a consistency issue from the installation guide audit. Since any changes would impact references and patches for other issues, I wanted to discuss the situation early in the process of improving the installation guide. Whatever we decide for filenames and IDs, it should go into our conventions page for future reference. On Mon, May 26, 2014 at 8:47 AM, Diane Fleming <diane.fleming at rackspace.com>wrote: > Matt, > > What problem are you trying to solve by updating the xml:id values? > > I'd start with one issue ? the file names ? and then figure out what you > want to accomplish by changing xml:id values. > > I personally don't see much value-add with updates to the ID's, but I > could be missing something! > > thanks, > > *Diane* > *----------------------------------------------* > Diane Fleming > Software Developer II - US > diane.fleming at rackspace.com > Cell 512.323.6799 > Office 512.874.1260 > Skype drfleming0227 > Google-plus diane.fleming at gmail.com > > From: Matt Kassawara <mkassawara at gmail.com> > Date: Monday, May 26, 2014 9:42 AM > To: Diane Fleming <diane.fleming at rackspace.com> > Cc: Anne Gentle <anne at openstack.org>, Andreas Jaeger <aj at suse.com>, " > openstack-docs at lists.openstack.org" <openstack-docs at lists.openstack.org> > Subject: Re: [Openstack-docs] Conventions for filenames and > chapter/section IDs > > How about describing the hierarchy in IDs, but not necessarily with > ch_, section_, etc? For example: > > ch_networking -> networking > section_neutron-networking-ml2 -> networking-neutron-ml2 > section_neutron-ml2-controller-node -> > networking-neutron-ml2-controller-node > > Also, would it help to indicate type in figure, table, and similar > element IDs? For example: > > example-architecture-with-legacy-networking -> > fig_example-architecture-with-legacy-networking > table1 -> tab_getstart-openstack-services (from common/ch_getstart.xml) > para3 -> par_getstart-3 (from common/ch_getstart.xml) > > Or... am I still the totally crazy noob? > > P.S. - I'm also interested in ideas for standardizing filenames and/or > locations for figures. > > > On Sun, May 25, 2014 at 5:59 PM, Diane Fleming < > diane.fleming at rackspace.com> wrote: > >> +1 for file name conventions >> -1 for xml:id conventions >> >> >> >> Sent from my iPhone >> >> On May 25, 2014, at 6:28 PM, "Anne Gentle" <anne at openstack.org> wrote: >> >> >> >> >> On Sun, May 25, 2014 at 4:50 PM, Steve Gordon <sgordon at redhat.com> wrote: >> >>> ----- Original Message ----- >>> > From: "Anne Gentle" <anne at openstack.org> >>> > To: "Andreas Jaeger" <aj at suse.com> >>> > >>> > Something to think about for ch and sec is that we won't always author >>> in a >>> > book-like manner, so let's not lock ourselves into that sort of >>> thinking >>> > due to current file names. >>> > >>> > Stick to the install guide for now, to apply conventions, just please >>> don't >>> > use something as meaningful semantically as chapter and section. >>> >>> I actually think it's important/useful information in the filename. It >>> reflects the root node of the file's XML which has an impact on where you >>> can nest/include it in another document (you can't include a chapter in a >>> section for example, but you can include a section in a chapter). It's got >>> more to do with the realities of the format being used than whether we're >>> thinking in terms of books, articles, etc. >>> >> >> I agree it's a useful codification in the file name, but I don't think >> we want it in the xml:id. The xml:id is used for SEO, for human-readable >> URLs, and so on. Let's not leak our abstraction further than we have to. :) >> Anne >> >> >>> >>> Granted if we moved to a non-XML format this would no longer be the >>> case, but I think we'd have bigger conversion issues than bulk renaming the >>> files/links. ;) >>> >>> -Steve >>> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/545c147a/attachment.html> From mkassawara at gmail.com Mon May 26 15:29:28 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Mon, 26 May 2014 09:29:28 -0600 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CFA8C4E9.2DFB0%diane.fleming@rackspace.com> References: <CABA+jQqq=9iQ4R5eMqmMpzS3HRQmq_6YXq7PPhbcT0+Hucs34Q@mail.gmail.com> <CFA8C4E9.2DFB0%diane.fleming@rackspace.com> Message-ID: <CABA+jQpsx6AqNC-7mzPPwLxuA74-+MVCZi_E8CnxUk85Ctm9kw@mail.gmail.com> During the Icehouse installation guide updates project, selection of IDs in new content confused me because I couldn't find conventions or anything consistent to follow. This caused me to bring up ID issues during the audit but didn't consider the underlying filename issues. For IDs, maybe we provide some good/bad examples, but otherwise leave it open to the contributor? At any rate, I'm glad this discussion revealed a larger problem that we want to fix... filenames! On Mon, May 26, 2014 at 9:17 AM, Diane Fleming <diane.fleming at rackspace.com>wrote: > Matt, > > I agree that whatever consistency issues we come up with should be > documented on conventions page. > > My suggestion was that you postpone thinking about the ID issue until > you come up with reasons for changing them. It seems like everyone agrees > on the file name changes, so I think it's safe to go forward with that! > > *Diane* > *----------------------------------------------* > Diane Fleming > Software Developer II - US > diane.fleming at rackspace.com > Cell 512.323.6799 > Office 512.874.1260 > Skype drfleming0227 > Google-plus diane.fleming at gmail.com > > From: Matt Kassawara <mkassawara at gmail.com> > Date: Monday, May 26, 2014 10:15 AM > To: Diane Fleming <diane.fleming at rackspace.com> > > Subject: Re: [Openstack-docs] Conventions for filenames and > chapter/section IDs > > IDs came up as a consistency issue from the installation guide audit. > Since any changes would impact references and patches for other issues, I > wanted to discuss the situation early in the process of improving the > installation guide. Whatever we decide for filenames and IDs, it should go > into our conventions page for future reference. > > > On Mon, May 26, 2014 at 8:47 AM, Diane Fleming < > diane.fleming at rackspace.com> wrote: > >> Matt, >> >> What problem are you trying to solve by updating the xml:id values? >> >> I'd start with one issue ? the file names ? and then figure out what >> you want to accomplish by changing xml:id values. >> >> I personally don't see much value-add with updates to the ID's, but I >> could be missing something! >> >> thanks, >> >> *Diane* >> *----------------------------------------------* >> Diane Fleming >> Software Developer II - US >> diane.fleming at rackspace.com >> Cell 512.323.6799 >> Office 512.874.1260 >> Skype drfleming0227 >> Google-plus diane.fleming at gmail.com >> >> From: Matt Kassawara <mkassawara at gmail.com> >> Date: Monday, May 26, 2014 9:42 AM >> To: Diane Fleming <diane.fleming at rackspace.com> >> Cc: Anne Gentle <anne at openstack.org>, Andreas Jaeger <aj at suse.com>, " >> openstack-docs at lists.openstack.org" <openstack-docs at lists.openstack.org> >> Subject: Re: [Openstack-docs] Conventions for filenames and >> chapter/section IDs >> >> How about describing the hierarchy in IDs, but not necessarily with >> ch_, section_, etc? For example: >> >> ch_networking -> networking >> section_neutron-networking-ml2 -> networking-neutron-ml2 >> section_neutron-ml2-controller-node -> >> networking-neutron-ml2-controller-node >> >> Also, would it help to indicate type in figure, table, and similar >> element IDs? For example: >> >> example-architecture-with-legacy-networking -> >> fig_example-architecture-with-legacy-networking >> table1 -> tab_getstart-openstack-services (from common/ch_getstart.xml) >> para3 -> par_getstart-3 (from common/ch_getstart.xml) >> >> Or... am I still the totally crazy noob? >> >> P.S. - I'm also interested in ideas for standardizing filenames and/or >> locations for figures. >> >> >> On Sun, May 25, 2014 at 5:59 PM, Diane Fleming < >> diane.fleming at rackspace.com> wrote: >> >>> +1 for file name conventions >>> -1 for xml:id conventions >>> >>> >>> >>> Sent from my iPhone >>> >>> On May 25, 2014, at 6:28 PM, "Anne Gentle" <anne at openstack.org> wrote: >>> >>> >>> >>> >>> On Sun, May 25, 2014 at 4:50 PM, Steve Gordon <sgordon at redhat.com>wrote: >>> >>>> ----- Original Message ----- >>>> > From: "Anne Gentle" <anne at openstack.org> >>>> > To: "Andreas Jaeger" <aj at suse.com> >>>> > >>>> > Something to think about for ch and sec is that we won't always >>>> author in a >>>> > book-like manner, so let's not lock ourselves into that sort of >>>> thinking >>>> > due to current file names. >>>> > >>>> > Stick to the install guide for now, to apply conventions, just please >>>> don't >>>> > use something as meaningful semantically as chapter and section. >>>> >>>> I actually think it's important/useful information in the filename. It >>>> reflects the root node of the file's XML which has an impact on where you >>>> can nest/include it in another document (you can't include a chapter in a >>>> section for example, but you can include a section in a chapter). It's got >>>> more to do with the realities of the format being used than whether we're >>>> thinking in terms of books, articles, etc. >>>> >>> >>> I agree it's a useful codification in the file name, but I don't think >>> we want it in the xml:id. The xml:id is used for SEO, for human-readable >>> URLs, and so on. Let's not leak our abstraction further than we have to. :) >>> Anne >>> >>> >>>> >>>> Granted if we moved to a non-XML format this would no longer be the >>>> case, but I think we'd have bigger conversion issues than bulk renaming the >>>> files/links. ;) >>>> >>>> -Steve >>>> >>> >>> _______________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.openstack.org >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>> >>> >>> _______________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.openstack.org >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>> >>> >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/97840a1d/attachment-0001.html> From nchase at mirantis.com Mon May 26 15:32:00 2014 From: nchase at mirantis.com (Nick Chase) Date: Mon, 26 May 2014 11:32:00 -0400 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <1965553805.18459527.1401054641947.JavaMail.zimbra@redhat.com> References: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> <53824983.3060301@suse.com> <CAD0KtVFPYs7LdCYUunnD5Yk1qvoCAcoUvjgkVDbW2YyuNSU0Xg@mail.gmail.com> <1965553805.18459527.1401054641947.JavaMail.zimbra@redhat.com> Message-ID: <CA+p99GkhBPhxsEzKeu=45DwYWuVfq=pozVKzTO2Tz7O6RM162A@mail.gmail.com> OK, so as I'm breaking out the HA chapter at this very minute, let me throw something else into the mix. The HA Guide is broken into 2 parts, each with a number of chapters, each with a number of sections. Right now I've broken it down into chapter files, but as I get down to the section level I begin to get overwhelmed with the number of files. Is there any objection to grouping section files in folders by chapter? For example: ch_aa_network.xml ch_aa_network/sec_run_neutron_dhcp_agent.xml I mean, I can just as easily make it ch_aa_network.xml sec_run_neutron_dhcp_agent.xml But it starts to get really messy. Thoughts? ---- Nick On Sun, May 25, 2014 at 5:50 PM, Steve Gordon <sgordon at redhat.com> wrote: > ----- Original Message ----- > > From: "Anne Gentle" <anne at openstack.org> > > To: "Andreas Jaeger" <aj at suse.com> > > > > Something to think about for ch and sec is that we won't always author > in a > > book-like manner, so let's not lock ourselves into that sort of thinking > > due to current file names. > > > > Stick to the install guide for now, to apply conventions, just please > don't > > use something as meaningful semantically as chapter and section. > > I actually think it's important/useful information in the filename. It > reflects the root node of the file's XML which has an impact on where you > can nest/include it in another document (you can't include a chapter in a > section for example, but you can include a section in a chapter). It's got > more to do with the realities of the format being used than whether we're > thinking in terms of books, articles, etc. > > Granted if we moved to a non-XML format this would no longer be the case, > but I think we'd have bigger conversion issues than bulk renaming the > files/links. ;) > > -Steve > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/fb151b87/attachment.html> From david.cramer at RACKSPACE.COM Mon May 26 15:43:52 2014 From: david.cramer at RACKSPACE.COM (David Cramer) Date: Mon, 26 May 2014 15:43:52 +0000 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs References: <CABA+jQoKAoy8OUtNNf1bwUK3jCRrYqGRx22NpH_eUuATgD0fig@mail.gmail.com> <CFA8BDF2.2DFA0%diane.fleming@rackspace.com> <CA+p99Gnwea4hT=bo4=W4sTOG4jVXjbi8VrgO8UmkmDx9c_WxuA@mail.gmail.com> Message-ID: <911A41E5F7881A4C8DE8BE32135554A9A1CB8C21@ORD1EXD01.RACKSPACE.CORP> On 5/26/14, 10:07 AM, Nick Chase wrote: > Plus my concern in changing Id values is breaking any references. You can reduce (but not eliminate) the impact of a file name change by changing the file names via a processing instruction: <section xml:id="some-dumb-id"><?dbhtml filename="intro.html"?>... If you use <?dbhtml filename="..."?> you'll get the aesthetically pleasing intro.html file name without having to change the xml:id and break xrefs to the section. However, if you have external links to some-dumb-id.html from other documents, those links would obviously break. Regardless of the publishing tool chain, when changing the names of existing resources on the web, the best approach is to add 301 redirects to avoid breaking bookmarks, links, and losing SEO karma. Regards, David From mkassawara at gmail.com Mon May 26 15:53:27 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Mon, 26 May 2014 09:53:27 -0600 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CA+p99GkhBPhxsEzKeu=45DwYWuVfq=pozVKzTO2Tz7O6RM162A@mail.gmail.com> References: <CABA+jQpWen3FsY-Qk4frNvXHQJf5ujO__pAMKVSOj090j5jsMA@mail.gmail.com> <CABA+jQoVRRtkDn8mqjLAW7SWwrx4z13oyC=3a693cyPoY9cW1A@mail.gmail.com> <53824983.3060301@suse.com> <CAD0KtVFPYs7LdCYUunnD5Yk1qvoCAcoUvjgkVDbW2YyuNSU0Xg@mail.gmail.com> <1965553805.18459527.1401054641947.JavaMail.zimbra@redhat.com> <CA+p99GkhBPhxsEzKeu=45DwYWuVfq=pozVKzTO2Tz7O6RM162A@mail.gmail.com> Message-ID: <CABA+jQrQdT92N6yV1kpLMGGUc3yCbR-VgLkyGyGaZgp0cLJeRw@mail.gmail.com> I like the idea of subdirectories. During the installation guide updates project, I broke the neutron content into smaller files to simplify editing and to reduce chances of patch collisions. However, this increased the overall number of files. Implementing subdirectories would mitigate this issue. The installation guide swift chapter already uses a subdirectory which I'm debating suggesting for the remainder of the installation guide and potentially other books. On Mon, May 26, 2014 at 9:32 AM, Nick Chase <nchase at mirantis.com> wrote: > OK, so as I'm breaking out the HA chapter at this very minute, let me > throw something else into the mix. The HA Guide is broken into 2 parts, > each with a number of chapters, each with a number of sections. Right now > I've broken it down into chapter files, but as I get down to the section > level I begin to get overwhelmed with the number of files. Is there any > objection to grouping section files in folders by chapter? For example: > > ch_aa_network.xml > ch_aa_network/sec_run_neutron_dhcp_agent.xml > > I mean, I can just as easily make it > > ch_aa_network.xml > sec_run_neutron_dhcp_agent.xml > > But it starts to get really messy. > > Thoughts? > > ---- Nick > > > > On Sun, May 25, 2014 at 5:50 PM, Steve Gordon <sgordon at redhat.com> wrote: > >> ----- Original Message ----- >> > From: "Anne Gentle" <anne at openstack.org> >> > To: "Andreas Jaeger" <aj at suse.com> >> > >> > Something to think about for ch and sec is that we won't always author >> in a >> > book-like manner, so let's not lock ourselves into that sort of thinking >> > due to current file names. >> > >> > Stick to the install guide for now, to apply conventions, just please >> don't >> > use something as meaningful semantically as chapter and section. >> >> I actually think it's important/useful information in the filename. It >> reflects the root node of the file's XML which has an impact on where you >> can nest/include it in another document (you can't include a chapter in a >> section for example, but you can include a section in a chapter). It's got >> more to do with the realities of the format being used than whether we're >> thinking in terms of books, articles, etc. >> >> Granted if we moved to a non-XML format this would no longer be the case, >> but I think we'd have bigger conversion issues than bulk renaming the >> files/links. ;) >> >> -Steve >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/791df983/attachment.html> From diane.fleming at RACKSPACE.COM Mon May 26 15:55:19 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Mon, 26 May 2014 15:55:19 +0000 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CABA+jQrQdT92N6yV1kpLMGGUc3yCbR-VgLkyGyGaZgp0cLJeRw@mail.gmail.com> Message-ID: <CFA8CE0C.2DFBF%diane.fleming@rackspace.com> +1 subdirectories Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com From: Matt Kassawara <mkassawara at gmail.com<mailto:mkassawara at gmail.com>> Date: Monday, May 26, 2014 10:53 AM To: Nick Chase <nchase at mirantis.com<mailto:nchase at mirantis.com>> Cc: Andreas Jaeger <aj at suse.com<mailto:aj at suse.com>>, "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>> Subject: Re: [Openstack-docs] Conventions for filenames and chapter/section IDs I like the idea of subdirectories. During the installation guide updates project, I broke the neutron content into smaller files to simplify editing and to reduce chances of patch collisions. However, this increased the overall number of files. Implementing subdirectories would mitigate this issue. The installation guide swift chapter already uses a subdirectory which I'm debating suggesting for the remainder of the installation guide and potentially other books. On Mon, May 26, 2014 at 9:32 AM, Nick Chase <nchase at mirantis.com<mailto:nchase at mirantis.com>> wrote: OK, so as I'm breaking out the HA chapter at this very minute, let me throw something else into the mix. The HA Guide is broken into 2 parts, each with a number of chapters, each with a number of sections. Right now I've broken it down into chapter files, but as I get down to the section level I begin to get overwhelmed with the number of files. Is there any objection to grouping section files in folders by chapter? For example: ch_aa_network.xml ch_aa_network/sec_run_neutron_dhcp_agent.xml I mean, I can just as easily make it ch_aa_network.xml sec_run_neutron_dhcp_agent.xml But it starts to get really messy. Thoughts? ---- Nick On Sun, May 25, 2014 at 5:50 PM, Steve Gordon <sgordon at redhat.com<mailto:sgordon at redhat.com>> wrote: ----- Original Message ----- > From: "Anne Gentle" <anne at openstack.org<mailto:anne at openstack.org>> > To: "Andreas Jaeger" <aj at suse.com<mailto:aj at suse.com>> > > Something to think about for ch and sec is that we won't always author in a > book-like manner, so let's not lock ourselves into that sort of thinking > due to current file names. > > Stick to the install guide for now, to apply conventions, just please don't > use something as meaningful semantically as chapter and section. I actually think it's important/useful information in the filename. It reflects the root node of the file's XML which has an impact on where you can nest/include it in another document (you can't include a chapter in a section for example, but you can include a section in a chapter). It's got more to do with the realities of the format being used than whether we're thinking in terms of books, articles, etc. Granted if we moved to a non-XML format this would no longer be the case, but I think we'd have bigger conversion issues than bulk renaming the files/links. ;) -Steve _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/86fc4365/attachment-0001.html> From nchase at mirantis.com Mon May 26 16:13:40 2014 From: nchase at mirantis.com (Nick Chase) Date: Mon, 26 May 2014 12:13:40 -0400 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <911A41E5F7881A4C8DE8BE32135554A9A1CB8C21@ORD1EXD01.RACKSPACE.CORP> References: <CABA+jQoKAoy8OUtNNf1bwUK3jCRrYqGRx22NpH_eUuATgD0fig@mail.gmail.com> <CFA8BDF2.2DFA0%diane.fleming@rackspace.com> <CA+p99Gnwea4hT=bo4=W4sTOG4jVXjbi8VrgO8UmkmDx9c_WxuA@mail.gmail.com> <911A41E5F7881A4C8DE8BE32135554A9A1CB8C21@ORD1EXD01.RACKSPACE.CORP> Message-ID: <CA+p99GnUAz0Z+CqzXutLAWkei51JjVp-H84AdYx+s6s_AHvPzA@mail.gmail.com> My concern on this is that it raises a barrier to entry for contributors. It's not intuitive. As a fix in an emergency, sure. But I'd be concerned about building this out as the standard way we do things. ---- Nick On Mon, May 26, 2014 at 11:43 AM, David Cramer <david.cramer at rackspace.com>wrote: > On 5/26/14, 10:07 AM, Nick Chase wrote: > > Plus my concern in changing Id values is breaking any references. > > You can reduce (but not eliminate) the impact of a file name change by > changing the file names via a processing instruction: > > <section xml:id="some-dumb-id"><?dbhtml filename="intro.html"?>... > > If you use <?dbhtml filename="..."?> you'll get the aesthetically > pleasing intro.html file name without having to change the xml:id and > break xrefs to the section. However, if you have external links to > some-dumb-id.html from other documents, those links would obviously break. > > Regardless of the publishing tool chain, when changing the names of > existing resources on the web, the best approach is to add 301 redirects > to avoid breaking bookmarks, links, and losing SEO karma. > > Regards, > David > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/8eaa2917/attachment.html> From nchase at mirantis.com Mon May 26 19:52:13 2014 From: nchase at mirantis.com (Nick Chase) Date: Mon, 26 May 2014 15:52:13 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <CA+p99GnrsU07jj7j+=bb7B0=k8_rPDnN2fQmNdN_WDC=D14jhg@mail.gmail.com> References: <CFA22EB5.2D9AB%diane.fleming@rackspace.com> <537CC933.6070106@mirantis.com> <CAD0KtVG3w49yuMt9GWT52SxkZSBqzJKqSwt6RuEJg273paxrJg@mail.gmail.com> <CABA+jQph8FUAjhmdknWJgQG5LZ7qP=ehsnM9JzjNxyqBGC3A8g@mail.gmail.com> <537CCDAE.50305@mirantis.com> <537CD385.10102@enovance.com> <CFA36D4C.1217%joseph.robinson@rackspace.com> <CA+p99GnhK4jY_db3sZg8XM5mFc=T6QXjWemLKaP7bx8jWe66-A@mail.gmail.com> <CABA+jQpATnb=eUC_dYJZM8AVgDACY9NHCoUhBB6Hesrqj1-o+w@mail.gmail.com> <CA+p99G=LNrtYb3-WOayV2Z9DZs3ui59WXJz6P-7UCk7VjWng-A@mail.gmail.com> <53824AA5.8020702@suse.com> <CA+p99GmMLGwQfzFPYmxuDRT9tP6SpOWpMVKcB2sx3S7dYWEf+w@mail.gmail.com> <CFA8BF47.13C7%joseph.robinson@rackspace.com> <CA+p99Gn3cBBKW1cXX1seXuoUfd7Ahn9vNLw=nL734T_kABwmpA@mail.gmail.com> <5382DE71.2080908@suse.com> <CA+p99GnrsU07jj7j+=bb7B0=k8_rPDnN2fQmNdN_WDC=D14jhg@mail.gmail.com> Message-ID: <CA+p99G=Gj3vx2mRwC1u74qS34VS1-Kw77HoPkMTG1tKNWdeSPQ@mail.gmail.com> OK, as soon as https://review.openstack.org/#/c/95401/ merges, I've got the files broken out by section and ready to go. ---- Nick On Mon, May 26, 2014 at 10:39 AM, Nick Chase <nchase at mirantis.com> wrote: > > On May 26, 2014 2:25 AM, "Andreas Jaeger" <aj at suse.com> wrote: > > > > On 05/26/2014 07:44 AM, Nick Chase wrote: > > > OK, so here's where we are: > > > > > > I've got one patch in that does the wholesale conversion to XML, but > > > doesn't have things broken down and audited yet. That's here: > > > > > > https://review.openstack.org/#/c/95401/ > > > > > > However, as you can see, it doesn't pass tox. It doesn't pass tox > > > locally because it's trying to convert it to docbook, and there's > > > nothing to convert. I've removed that functionality from os-docs-tools > > > here: > > > > > > https://review.openstack.org/#/c/95406/ > > > > > > But that needs to be merged before I can run tox on the book to look > for > > > other problems. I think. > > > > Agreed. I should have read my whole INBOX before patching and answering > ;) > > If you're like me you'd never get anything done that way. :) > > > > Anyway, I've just commented code here; I'm happy to actually delete it > > > if I've done the right thing, but I didn't want to just hack out a > bunch > > > of code without someone more familiar looking at it first. > > > > You commented out too much in that file and missed the parts that > > actually builds the books, I've updated your patch. > > And that's why I commented instead of deleting. :) Thanks for the assist. > > Anyway I've got the next one, which breaks it all down to the section > level, just about ready to go. Then i can do cleanup. > > ---- Nick > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140526/2d7be7ed/attachment.html> From gauvain.pocentek at objectif-libre.com Tue May 27 15:15:16 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Tue, 27 May 2014 17:15:16 +0200 Subject: [Openstack-docs] [openstack-dev] [Heat][Documentation] Heat template documentation In-Reply-To: <CAD0KtVEyJmezeHhQqZXBwUwS9-cbafYp9sCcEp=ybiWuiKtUzw@mail.gmail.com> References: <CAD0KtVF6qnO4-Kd7ELxJZU53r7jtTSv7mCJG3ZVyJu-C+LxtYA@mail.gmail.com> <37903930f5456fa6f09066fe41cce960@objectif-libre.com> <CADb+p3RJ=cO0BxRsp7p=QiScS72dg5+ruz4WFZS9ZqyjE3sYcA@mail.gmail.com> <537BE872.3090509@redhat.com> <CAD0KtVHiqMgEq-A3ozq2ZVx3PtAZ=jwUnWHfa=pht5WXnLMHtA@mail.gmail.com> <537E6B94.1090806@redhat.com> <20140523101315.GA22280@t430slt.redhat.com> <537F2530.8010905@suse.com> <20140523111957.GB22280@t430slt.redhat.com> <CAD0KtVHP_=Og1uyL_p_k0+5nSk-8mJHFtOPbXqu-mO8R7QXg8Q@mail.gmail.com> <20140523134251.GC22280@t430slt.redhat.com> <CAD0KtVEyJmezeHhQqZXBwUwS9-cbafYp9sCcEp=ybiWuiKtUzw@mail.gmail.com> Message-ID: <f27ea5d694bbb2f800575c22266f0d39@objectif-libre.com> Le 2014-05-23 15:57, Anne Gentle a ?crit?: > On Fri, May 23, 2014 at 8:42 AM, Steven Hardy <shardy at redhat.com> > wrote: > >> On Fri, May 23, 2014 at 08:09:06AM -0500, Anne Gentle wrote: >>> On Fri, May 23, 2014 at 6:19 AM, Steven Hardy <shardy at redhat.com> >>> wrote: >>> >>>> On Fri, May 23, 2014 at 12:38:40PM +0200, Andreas Jaeger wrote: >>>>> On 05/23/2014 12:13 PM, Steven Hardy wrote: >>>>>> [...] >>>>>> I'll hold my hand up as one developer who tried to contribute but >>>>>> ran >>>> away >>>>>> screaming due to all the XML-java-ness of the current process. >>>>>> I don't think markup complexity is a major barrier to >>>>>> contribution. >>>> Needing >>>>>> to use a closed source editor and download unfathomably huge >>>>>> amounts of >>>>>> java to build locally definitely are though IMO/IME. >>>>> You do not need a closed sourced editor for XML - I'm using emacs >>>>> and >>>>> others in the team use vi for it. >>>> Sure, maybe "need" was the wrong word to use, my apologies. >>>> ?Regardless, >>>> the docs refer to a closed source tool being "encouraged", which >>>> immediately discouraged me when trying to figure out the workflow. >>>> I've tried editing XML in vim a few times, and although it's >>>> obviously >>>> possible, it's far less painful when I'm dealing with other more >>>> human-friendly formats. >>>> >>>>> Yes, it downloads a lot Java once. We also now build the documents >>>>> as >>>>> part of the gate, so you can also check changes by clicking the >>>>> "checkbuild" target, it will show you the converted books, >>>> Sure, that's good, but my (and I'd guess many others) preference is >>>> for >>>> formats which can be easily built locally with only distro-provided >>>> tools, >>>> not a huge pile of third party java. >>>> Not trying to start a format-advocacy argument here, just trying to >>>> provide >>>> a data-point that, if the success criteria is developer >>>> participation in >>>> the docs process, then the current toolchain is definitely a >>>> barrier to >>>> participation for some potential contributors. >>>> >>> >>> Thanks for the discussions -- let's keep a tone of civility. >>> Understand >>> that doc writers have specific tools that work well for them. That >>> said, we >>> do want to collaborate more with our end users specifically. >> My apologies if my remarks have been interpreted as uncivil, that was >> definitely not my intention. > Oh no not at all, sorry -- my intent is that we are all staying civil > and it's good. :) > ? > >> The only point I really wanted to convey was +1 on trying out an >> easier >> markup, and thanks for bringing up the topic of a user orientated >> orchestration guide - I would definitely like to contribute to the >> effort. > So we're still a little stuck on the tradeoffs -- with easier markup > we lose some features.? > For other generated reference docs, we maintain a set of python > scripts in openstack-doc-tools. Is it possible for someone to look > into generating the Heat template reference information outside of > Sphinx? Yes, I can look into that. The idea would be to generate some docbook from RST... So why not do it for the whole to-be-written heat user guide in that case? What I get from this thread is that 1) docbook is the best format to use to generate a nice and feature-rich output, 2) developers don't want to write docbook. Without being able to handle a different format developers will no contribute, which is bad because they want, and we want them to contribute :) So my feeling is that we should work on the tools to convert RST (or whatever format, but RST seems to be the "norm" for openstack projects) to docbook, and generate our online documentation from there. There are tools that can help us doing that, and I don't see an other solution that would make us move forward. Anne, you talked about experimenting with the end user guide, and after the discussion and the technical info brought by Doug, Steve and Steven, I now think it is worth trying. Thoughts? Gauvain From aj at suse.com Tue May 27 19:01:56 2014 From: aj at suse.com (Andreas Jaeger) Date: Tue, 27 May 2014 21:01:56 +0200 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <537CACFE.7090604@b1-systems.de> References: <537CACFE.7090604@b1-systems.de> Message-ID: <5384E124.3020201@suse.com> On 05/21/2014 03:41 PM, Christian Berendt wrote: > Even I like AsciiDoc I would suggest to convert the HA guide from > AsciiDoc to DocBook. All other guides are written in DocBox and I don't > see any benefit of keeping the HA guide in AsciiDoc. FYI, the patch by Nick has just been merged! This needs version 0.15 of the openstack-doc-tools. Anne just released the version. So, if you build locally, remember that you don't need to convert from asciidoc to docbook anymore - and if you use openstack-doc-tools, you need the 0.15 version for taking care of this. Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From nchase at mirantis.com Tue May 27 19:11:14 2014 From: nchase at mirantis.com (Nicholas Chase) Date: Tue, 27 May 2014 15:11:14 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <5384E124.3020201@suse.com> References: <537CACFE.7090604@b1-systems.de> <5384E124.3020201@suse.com> Message-ID: <5384E352.3030109@mirantis.com> Yay! OK, now I've got a question for you git folks out there. Yesterday, I did the next step in this process, breaking everything down by chapter and section. I got so far as to commit, but I decided to wait before hitting "git review". Today those files are GONE. Looks like my working copy has reset itself to an earlier version. I can redo it, but it took quite a while so I'd prefer to just retrieve it somehow. Does anybody have any ideas? Thanks... ---- Nick On 5/27/2014 3:01 PM, Andreas Jaeger wrote: > On 05/21/2014 03:41 PM, Christian Berendt wrote: >> Even I like AsciiDoc I would suggest to convert the HA guide from >> AsciiDoc to DocBook. All other guides are written in DocBox and I don't >> see any benefit of keeping the HA guide in AsciiDoc. > > FYI, the patch by Nick has just been merged! > > This needs version 0.15 of the openstack-doc-tools. Anne just released > the version. So, if you build locally, remember that you don't need to > convert from asciidoc to docbook anymore - and if you use > openstack-doc-tools, you need the 0.15 version for taking care of this. > > Andreas > From aj at suse.com Tue May 27 20:27:50 2014 From: aj at suse.com (Andreas Jaeger) Date: Tue, 27 May 2014 22:27:50 +0200 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <5384E352.3030109@mirantis.com> References: <537CACFE.7090604@b1-systems.de> <5384E124.3020201@suse.com> <5384E352.3030109@mirantis.com> Message-ID: <5384F546.2010707@suse.com> On 05/27/2014 09:11 PM, Nicholas Chase wrote: > Yay! OK, now I've got a question for you git folks out there. > > Yesterday, I did the next step in this process, breaking everything down > by chapter and section. I got so far as to commit, but I decided to > wait before hitting "git review". > > Today those files are GONE. Looks like my working copy has reset itself > to an earlier version. > > I can redo it, but it took quite a while so I'd prefer to just retrieve > it somehow. Does anybody have any ideas? > > Thanks... Are you working on a separate branch for this and just need to switch to it? IF not, do it next time ;) If you commit it, is it on your master branch, just not at the top of it? Run "git log" and search whether you can find it. Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From nchase at mirantis.com Tue May 27 20:35:05 2014 From: nchase at mirantis.com (Nicholas Chase) Date: Tue, 27 May 2014 16:35:05 -0400 Subject: [Openstack-docs] convert the HA guide from AsciiDoc to DocBook In-Reply-To: <5384F546.2010707@suse.com> References: <537CACFE.7090604@b1-systems.de> <5384E124.3020201@suse.com> <5384E352.3030109@mirantis.com> <5384F546.2010707@suse.com> Message-ID: <5384F6F9.9050902@mirantis.com> The weird thing is that I DID switch to a branch to work on it, but I'm not seeing the branch anywhere, even though I was able to see it yesterday when I listed branches. ---- Nick On 5/27/2014 4:27 PM, Andreas Jaeger wrote: > On 05/27/2014 09:11 PM, Nicholas Chase wrote: >> Yay! OK, now I've got a question for you git folks out there. >> >> Yesterday, I did the next step in this process, breaking everything down >> by chapter and section. I got so far as to commit, but I decided to >> wait before hitting "git review". >> >> Today those files are GONE. Looks like my working copy has reset itself >> to an earlier version. >> >> I can redo it, but it took quite a while so I'd prefer to just retrieve >> it somehow. Does anybody have any ideas? >> >> Thanks... > > > Are you working on a separate branch for this and just need to switch to > it? IF not, do it next time ;) > > If you commit it, is it on your master branch, just not at the top of > it? Run "git log" and search whether you can find it. > > Andreas > From openstack at lanabrindley.com Tue May 27 23:35:59 2014 From: openstack at lanabrindley.com (Lana Brindley) Date: Wed, 28 May 2014 09:35:59 +1000 Subject: [Openstack-docs] APAC docs meeting CANCELLED Message-ID: <5385215F.7040102@lanabrindley.com> Heya everyone, Unless someone (Summer?) can stand up to be chair at the last minute, I'm afraid I have to cancel today's APAC OpenStack docs meeting, as I have a conflict. I'll see you in two weeks o/ L -- Lana Brindley Technical Writer Rackspace Cloud Builders Australia http://lanabrindley.com From mkassawara at gmail.com Tue May 27 23:42:57 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Tue, 27 May 2014 17:42:57 -0600 Subject: [Openstack-docs] APAC docs meeting CANCELLED In-Reply-To: <5385215F.7040102@lanabrindley.com> References: <5385215F.7040102@lanabrindley.com> Message-ID: <CABA+jQqm1=_5C=dQC3Os8FMCnuF8Qq8rMmwfee0Da5mqnhgNjA@mail.gmail.com> I can chair the meeting. Please add any topics to the wiki page. https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting#Agenda_for_next_meeting On Tue, May 27, 2014 at 5:35 PM, Lana Brindley <openstack at lanabrindley.com>wrote: > Heya everyone, > > Unless someone (Summer?) can stand up to be chair at the last minute, I'm > afraid I have to cancel today's APAC OpenStack docs meeting, as I have a > conflict. > > I'll see you in two weeks o/ > > L > > -- > Lana Brindley > Technical Writer > Rackspace Cloud Builders Australia > http://lanabrindley.com > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140527/1f0491d0/attachment.html> From anne at openstack.org Wed May 28 04:04:10 2014 From: anne at openstack.org (Anne Gentle) Date: Tue, 27 May 2014 23:04:10 -0500 Subject: [Openstack-docs] Alternating meetings Wed. Message-ID: <CAD0KtVFXHTiTsaXk-re+QAdKH_5kwcYuWP+2+jgUWPZ_3kizkQ@mail.gmail.com> Hi all, Typically I rely on the ical feed to tell me when the Docs team meeting is, but it seems that the ical feed thinks the North America meeting is the 1st and 3rd Wed. and it had "forgotten" the APAC meeting. I've now coerced it to remember the APAC meeting as 0300 UTC on the 2nd and 4th Wed. I hope this fits reality and we can run an APAC meeting tomorrow. Let me know - Thanks, Anne -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140527/14c6e760/attachment-0001.html> From gauvain.pocentek at objectif-libre.com Wed May 28 05:17:41 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Wed, 28 May 2014 07:17:41 +0200 Subject: [Openstack-docs] [openstack-dev] [Heat][Documentation] Heat template documentation In-Reply-To: <53853639.2020506@redhat.com> References: <CAD0KtVF6qnO4-Kd7ELxJZU53r7jtTSv7mCJG3ZVyJu-C+LxtYA@mail.gmail.com> <37903930f5456fa6f09066fe41cce960@objectif-libre.com> <CADb+p3RJ=cO0BxRsp7p=QiScS72dg5+ruz4WFZS9ZqyjE3sYcA@mail.gmail.com> <537BE872.3090509@redhat.com> <CAD0KtVHiqMgEq-A3ozq2ZVx3PtAZ=jwUnWHfa=pht5WXnLMHtA@mail.gmail.com> <537E6B94.1090806@redhat.com> <20140523101315.GA22280@t430slt.redhat.com> <537F2530.8010905@suse.com> <20140523111957.GB22280@t430slt.redhat.com> <CAD0KtVHP_=Og1uyL_p_k0+5nSk-8mJHFtOPbXqu-mO8R7QXg8Q@mail.gmail.com> <20140523134251.GC22280@t430slt.redhat.com> <CAD0KtVEyJmezeHhQqZXBwUwS9-cbafYp9sCcEp=ybiWuiKtUzw@mail.gmail.com> <f27ea5d694bbb2f800575c22266f0d39@objectif-libre.com> <53853639.2020506@redhat.com> Message-ID: <0ffd733cc476e5b3ed39bb5be83bd5f7@objectif-libre.com> Le 2014-05-28 03:04, Steve Baker a ?crit?: > On 28/05/14 03:15, Gauvain Pocentek wrote: >> Le 2014-05-23 15:57, Anne Gentle a ?crit : >>> On Fri, May 23, 2014 at 8:42 AM, Steven Hardy <shardy at redhat.com> >>> wrote: >>> >>>> On Fri, May 23, 2014 at 08:09:06AM -0500, Anne Gentle wrote: >>>>> On Fri, May 23, 2014 at 6:19 AM, Steven Hardy <shardy at redhat.com> >>>>> wrote: >>>>> >>>>>> On Fri, May 23, 2014 at 12:38:40PM +0200, Andreas Jaeger wrote: >>>>>>> On 05/23/2014 12:13 PM, Steven Hardy wrote: >>>>>>>> [...] >>>>>>>> I'll hold my hand up as one developer who tried to contribute >>>>>>>> but ran >>>>>> away >>>>>>>> screaming due to all the XML-java-ness of the current process. >>>>>>>> I don't think markup complexity is a major barrier to >>>>>>>> contribution. >>>>>> Needing >>>>>>>> to use a closed source editor and download unfathomably huge >>>>>>>> amounts of >>>>>>>> java to build locally definitely are though IMO/IME. >>>>>>> You do not need a closed sourced editor for XML - I'm using >>>>>>> emacs >>>>>>> and >>>>>>> others in the team use vi for it. >>>>>> Sure, maybe "need" was the wrong word to use, my apologies. >>>>>> Regardless, >>>>>> the docs refer to a closed source tool being "encouraged", which >>>>>> immediately discouraged me when trying to figure out the >>>>>> workflow. >>>>>> I've tried editing XML in vim a few times, and although it's >>>>>> obviously >>>>>> possible, it's far less painful when I'm dealing with other more >>>>>> human-friendly formats. >>>>>> >>>>>>> Yes, it downloads a lot Java once. We also now build the >>>>>>> documents as >>>>>>> part of the gate, so you can also check changes by clicking the >>>>>>> "checkbuild" target, it will show you the converted books, >>>>>> Sure, that's good, but my (and I'd guess many others) preference >>>>>> is for >>>>>> formats which can be easily built locally with only >>>>>> distro-provided tools, >>>>>> not a huge pile of third party java. >>>>>> Not trying to start a format-advocacy argument here, just trying >>>>>> to provide >>>>>> a data-point that, if the success criteria is developer >>>>>> participation in >>>>>> the docs process, then the current toolchain is definitely a >>>>>> barrier to >>>>>> participation for some potential contributors. >>>>>> >>>>> >>>>> Thanks for the discussions -- let's keep a tone of civility. >>>>> Understand >>>>> that doc writers have specific tools that work well for them. That >>>>> said, we >>>>> do want to collaborate more with our end users specifically. >>>> My apologies if my remarks have been interpreted as uncivil, that >>>> was >>>> definitely not my intention. >>> Oh no not at all, sorry -- my intent is that we are all staying >>> civil >>> and it's good. :) >>> >>> >>>> The only point I really wanted to convey was +1 on trying out an >>>> easier >>>> markup, and thanks for bringing up the topic of a user orientated >>>> orchestration guide - I would definitely like to contribute to the >>>> effort. >>> So we're still a little stuck on the tradeoffs -- with easier markup >>> we lose some features. >>> For other generated reference docs, we maintain a set of python >>> scripts in openstack-doc-tools. Is it possible for someone to look >>> into generating the Heat template reference information outside of >>> Sphinx? >> >> Yes, I can look into that. >> >> The idea would be to generate some docbook from RST... So why not do >> it for the whole to-be-written heat user guide in that case? >> >> What I get from this thread is that 1) docbook is the best format to >> use to generate a nice and feature-rich output, 2) developers don't >> want to write docbook. Without being able to handle a different >> format >> developers will no contribute, which is bad because they want, and we >> want them to contribute :) >> >> So my feeling is that we should work on the tools to convert RST (or >> whatever format, but RST seems to be the "norm" for openstack >> projects) to docbook, and generate our online documentation from >> there. There are tools that can help us doing that, and I don't see >> an >> other solution that would make us move forward. >> >> Anne, you talked about experimenting with the end user guide, and >> after the discussion and the technical info brought by Doug, Steve >> and >> Steven, I now think it is worth trying. >> > In this vein, I enabled the sphinx xml builder in heat: > https://review.openstack.org/#/c/95979/ > > And here is a sample of the output: > http://paste.openstack.org/show/81811/ > http://paste.openstack.org/show/81812/ > > This looks like it could be readily transformed into DocBook via XSL. http://ebellot.chez.com/dn2dbk/index.htm could be used as a starting point. It generates docbook 4, but can probably be easily modified to generate docbook 5, adapted to our conventions. The doc is in french, if anyone's interested I can do a quick translation of the important parts. > Alternatively we could write a Docutils writer which writes docbook > directly, possibly using this as a starting point: > http://docutils.sourceforge.net/sandbox/oliverr/docbook/ > > Any takers to start playing with this? I need to dive into docutils writers to understand/maintain an internal tool of ours, so /me volunteers. I also looked at how pandoc handles the RST -> docbook conversion, but I don't think it's not good enough for our needs. I'll play with these tools this week to see which one is the best option for us. Thanks! Gauvain From aj at suse.com Wed May 28 07:02:19 2014 From: aj at suse.com (Andreas Jaeger) Date: Wed, 28 May 2014 09:02:19 +0200 Subject: [Openstack-docs] Merging glossary back from O'Reilly guide with indexterms? Message-ID: <538589FB.60407@suse.com> The glossary in the O'Reilly guide has now lots of indexterm. To keep operations-guide and openstack-manuals in sync, I suggest to sync these - and thus include all the indexterms also in the openstack-manuals glossary. Any better suggestions? Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Wed May 28 08:20:17 2014 From: aj at suse.com (Andreas Jaeger) Date: Wed, 28 May 2014 10:20:17 +0200 Subject: [Openstack-docs] Japanese End User Guide and Admin User Guide Message-ID: <53859C41.9060706@suse.com> The Japanese team has done a great job translating these two guides! I just tried to build them and got hit by build errors. Could somebody investigate this, please? Once it works again, tell me and I can enable testing and publishing in openstack-manuals. I filled a bug for tracking: https://bugs.launchpad.net/openstack-i18n/+bug/1324007 Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Wed May 28 14:04:22 2014 From: anne at openstack.org (Anne Gentle) Date: Wed, 28 May 2014 09:04:22 -0500 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CA+p99GnUAz0Z+CqzXutLAWkei51JjVp-H84AdYx+s6s_AHvPzA@mail.gmail.com> References: <CABA+jQoKAoy8OUtNNf1bwUK3jCRrYqGRx22NpH_eUuATgD0fig@mail.gmail.com> <CFA8BDF2.2DFA0%diane.fleming@rackspace.com> <CA+p99Gnwea4hT=bo4=W4sTOG4jVXjbi8VrgO8UmkmDx9c_WxuA@mail.gmail.com> <911A41E5F7881A4C8DE8BE32135554A9A1CB8C21@ORD1EXD01.RACKSPACE.CORP> <CA+p99GnUAz0Z+CqzXutLAWkei51JjVp-H84AdYx+s6s_AHvPzA@mail.gmail.com> Message-ID: <CAD0KtVEm4pEwP2RVPah20SgjSruALXq9Cpq-imHsThnMrkbUug@mail.gmail.com> Here's what I'll update in the Documentation/Conventions page if everyone agrees: For file names, use bk_ ch_ and sec_ at the beginning of the file name to indicate the type of file it is in the hierarchy of the build. For further organization, you can use subdirectories to organize the files by a particular grouping such as project or topic. For xml:id creation, follow these guidelines. - xml:id must be unique across a built deliverable, otherwise you get build errors - xml:id creates the HTML file name so it should be human-readable, not codified like the file name - xml:id should closely follow the actual title in the text, using dashes for spaces - xml:id creation should consider search and find-ability as well as human-readability I prefer not to document the use a processing instruction like <?dbhtml filename="name"> as that should be the rare exception. Thanks, Anne On Mon, May 26, 2014 at 11:13 AM, Nick Chase <nchase at mirantis.com> wrote: > My concern on this is that it raises a barrier to entry for contributors. > It's not intuitive. As a fix in an emergency, sure. But I'd be concerned > about building this out as the standard way we do things. > > ---- Nick > > > On Mon, May 26, 2014 at 11:43 AM, David Cramer <david.cramer at rackspace.com > > wrote: > >> On 5/26/14, 10:07 AM, Nick Chase wrote: >> > Plus my concern in changing Id values is breaking any references. >> >> You can reduce (but not eliminate) the impact of a file name change by >> changing the file names via a processing instruction: >> >> <section xml:id="some-dumb-id"><?dbhtml filename="intro.html"?>... >> >> If you use <?dbhtml filename="..."?> you'll get the aesthetically >> pleasing intro.html file name without having to change the xml:id and >> break xrefs to the section. However, if you have external links to >> some-dumb-id.html from other documents, those links would obviously break. >> >> Regardless of the publishing tool chain, when changing the names of >> existing resources on the web, the best approach is to add 301 redirects >> to avoid breaking bookmarks, links, and losing SEO karma. >> >> Regards, >> David >> >> > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140528/d517f9c0/attachment.html> From anne at openstack.org Wed May 28 14:09:25 2014 From: anne at openstack.org (Anne Gentle) Date: Wed, 28 May 2014 09:09:25 -0500 Subject: [Openstack-docs] What's Up Doc? May 28 2014 Message-ID: <CAD0KtVE+BCgDHNuozWfCCrAeAxLy-j3W7nP3AWtvmntZWnUo_Q@mail.gmail.com> Here's the latest news in docland. Thanks for all the great input at the Summit and excellent follow up conversations on the mailing lists. 1. In review and merged recently: Conversion of the High Availability Guide to DocBook to ease maintenance. It's so interesting that the conversation about the End User Guide and adding Heat Template information has Julien suggesting asciidoc -- we haven't seen an uptick in contributions to the single asciidoc file we had in the repo. But it's an unfair comparison since High Availability is a specialty that not many would have contributed to. So let's keep talking about the priorities for authoring ease. Addition of roadmap.rst to each guide's directory. You can see what tasks are not large enough to merit a blueprint but are still needed work on any given guide. Also note that the <project>-specs repos were rumored to be renamed to <program>-specs, but they are going to remain <project>-specs. I haven't been compelled to create a docs-specs repo and instead went with the roadmap file mentioned above. The database-api repository is now deleted and the API documentation for the trove project now lives in the trove repository. Thanks for the interest and let's keep doing that move for all the projects. 2. High priority doc work: I've re-started an effort to bring in the O'Reilly content with index entries wholesale at https://review.openstack.org/#/c/96015/ - let's merge quickly so that rebasing isn't so difficult and so we can merge in the havana to icehouse upgrade information. The Architecture design guide book sprint is being planned by Ken Hui and we have enough authors as of now but he is wait listing so do contact him if you're interested. The dates are July 7-11 and VMware is hosting in Palo Alto. Still working on persona definitions for the Documentation so that the intended audience can be added to each guide in the front matter. Also we're working on further organizing the Documentation/HowTo wiki page to encourage newcomers. The Security Guide will be moving to its own repository with a separate core review team. Thanks all for the interest there! 3. Doc work going on that I know of: We're continuing discussions about the User Guide to see if we can automate some of the Orchestration reference information and incorporate into the End User Guide or Admin User Guide. Matt is working on writing up standards for file names and xml:ids as part of the install guide work. Follow along at http://lists.openstack.org/pipermail/openstack-docs/2014-May/004471.html. 4. New incoming doc requests: I'd like to get started on app developer documentation and have been talking to various community members from HP and other places. I'm also meeting with Todd Morey, the Foundation designer who originally desiged docs.openstack.org, this week for design ideas for docs. 5. Doc tools updates: The Maven Clouddocs plugin is at 2.0.2 now, and openstack-doc-tools is at 0.15. With 2.0.2 you can use markup within a code listing to emphasize (with bold output) anything you want to highlight in what's returned to the user. There's now a "checklang" non-voting gate test to test translations. When those break, please contact the openstack-docs list. Andreas has file this bug for further investigation and tracking: https://bugs.launchpad.net/ openstack-i18n/+bug/1324007 3:05 AM (5 hours ago) 6. Other doc news: I still want to have the discussion about moving the training guides out of the openstack-manuals repo with a separate core review team similar to the Security Guide. Let me know about good next steps there and we can make a plan. -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140528/39561157/attachment.html> From diane.fleming at RACKSPACE.COM Wed May 28 14:10:14 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Wed, 28 May 2014 14:10:14 +0000 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CAD0KtVEm4pEwP2RVPah20SgjSruALXq9Cpq-imHsThnMrkbUug@mail.gmail.com> Message-ID: <CFAB57AE.2E379%diane.fleming@rackspace.com> That looks good. My only change would be that sections should be section_*, only because that's how most of them are named at the moment so it would save a lot of work to keep what we already have. I have also used created other files for content sharing, such as itemized lists or tables. I usually prefix the file name with the object type in the file. itemizedlist_service_list.xml (for example) table_server_status.xml Oh, and for prefaces, I just use preface.xml Diane ---------------------------------------------- Diane Fleming Software Developer II - US diane.fleming at rackspace.com Cell 512.323.6799 Office 512.874.1260 Skype drfleming0227 Google-plus diane.fleming at gmail.com From: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>> Date: Wednesday, May 28, 2014 9:04 AM To: Nick Chase <nchase at mirantis.com<mailto:nchase at mirantis.com>> Cc: Andreas Jaeger <aj at suse.com<mailto:aj at suse.com>>, "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>> Subject: Re: [Openstack-docs] Conventions for filenames and chapter/section IDs Here's what I'll update in the Documentation/Conventions page if everyone agrees: For file names, use bk_ ch_ and sec_ at the beginning of the file name to indicate the type of file it is in the hierarchy of the build. For further organization, you can use subdirectories to organize the files by a particular grouping such as project or topic. For xml:id creation, follow these guidelines. - xml:id must be unique across a built deliverable, otherwise you get build errors - xml:id creates the HTML file name so it should be human-readable, not codified like the file name - xml:id should closely follow the actual title in the text, using dashes for spaces - xml:id creation should consider search and find-ability as well as human-readability I prefer not to document the use a processing instruction like <?dbhtml filename="name"> as that should be the rare exception. Thanks, Anne On Mon, May 26, 2014 at 11:13 AM, Nick Chase <nchase at mirantis.com<mailto:nchase at mirantis.com>> wrote: My concern on this is that it raises a barrier to entry for contributors. It's not intuitive. As a fix in an emergency, sure. But I'd be concerned about building this out as the standard way we do things. ---- Nick On Mon, May 26, 2014 at 11:43 AM, David Cramer <david.cramer at rackspace.com<mailto:david.cramer at rackspace.com>> wrote: On 5/26/14, 10:07 AM, Nick Chase wrote: > Plus my concern in changing Id values is breaking any references. You can reduce (but not eliminate) the impact of a file name change by changing the file names via a processing instruction: <section xml:id="some-dumb-id"><?dbhtml filename="intro.html"?>... If you use <?dbhtml filename="..."?> you'll get the aesthetically pleasing intro.html file name without having to change the xml:id and break xrefs to the section. However, if you have external links to some-dumb-id.html from other documents, those links would obviously break. Regardless of the publishing tool chain, when changing the names of existing resources on the web, the best approach is to add 301 redirects to avoid breaking bookmarks, links, and losing SEO karma. Regards, David _______________________________________________ Openstack-docs mailing list Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140528/101b742b/attachment-0001.html> From anne at openstack.org Wed May 28 14:20:00 2014 From: anne at openstack.org (Anne Gentle) Date: Wed, 28 May 2014 09:20:00 -0500 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CFAB57AE.2E379%diane.fleming@rackspace.com> References: <CAD0KtVEm4pEwP2RVPah20SgjSruALXq9Cpq-imHsThnMrkbUug@mail.gmail.com> <CFAB57AE.2E379%diane.fleming@rackspace.com> Message-ID: <CAD0KtVFD9RQa6Ct_dnHU8Ly60_+eYWWzoSN5tOx_dYZXO-42CA@mail.gmail.com> On Wed, May 28, 2014 at 9:10 AM, Diane Fleming <diane.fleming at rackspace.com>wrote: > That looks good. > > My only change would be that sections should be section_*, only because > that's how most of them are named at the moment so it would save a lot of > work to keep what we already have. > Ha, oops, I should have known that, sorry. > > I have also used created other files for content sharing, such as > itemized lists or tables. I usually prefix the file name with the object > type in the file. > > itemizedlist_service_list.xml (for example) > table_server_status.xml > > Makes sense. The table_prefix is very helpful. > Oh, and for prefaces, I just use > > preface.xml > > Ok, I'll note in the wiki page. Thanks! > > *Diane* > *----------------------------------------------* > Diane Fleming > Software Developer II - US > diane.fleming at rackspace.com > Cell 512.323.6799 > Office 512.874.1260 > Skype drfleming0227 > Google-plus diane.fleming at gmail.com > > From: Anne Gentle <anne at openstack.org> > Date: Wednesday, May 28, 2014 9:04 AM > > To: Nick Chase <nchase at mirantis.com> > Cc: Andreas Jaeger <aj at suse.com>, "openstack-docs at lists.openstack.org" < > openstack-docs at lists.openstack.org> > Subject: Re: [Openstack-docs] Conventions for filenames and > chapter/section IDs > > Here's what I'll update in the Documentation/Conventions page if > everyone agrees: > > For file names, use bk_ ch_ and sec_ at the beginning of the file name > to indicate the type of file it is in the hierarchy of the build. For > further organization, you can use subdirectories to organize the files by a > particular grouping such as project or topic. > > For xml:id creation, follow these guidelines. > - xml:id must be unique across a built deliverable, otherwise you get > build errors > - xml:id creates the HTML file name so it should be human-readable, not > codified like the file name > - xml:id should closely follow the actual title in the text, using dashes > for spaces > - xml:id creation should consider search and find-ability as well as > human-readability > > I prefer not to document the use a processing instruction like <?dbhtml > filename="name"> as that should be the rare exception. > > Thanks, > Anne > > > On Mon, May 26, 2014 at 11:13 AM, Nick Chase <nchase at mirantis.com> wrote: > >> My concern on this is that it raises a barrier to entry for contributors. >> It's not intuitive. As a fix in an emergency, sure. But I'd be concerned >> about building this out as the standard way we do things. >> >> ---- Nick >> >> >> On Mon, May 26, 2014 at 11:43 AM, David Cramer < >> david.cramer at rackspace.com> wrote: >> >>> On 5/26/14, 10:07 AM, Nick Chase wrote: >>> > Plus my concern in changing Id values is breaking any references. >>> >>> You can reduce (but not eliminate) the impact of a file name change by >>> changing the file names via a processing instruction: >>> >>> <section xml:id="some-dumb-id"><?dbhtml filename="intro.html"?>... >>> >>> If you use <?dbhtml filename="..."?> you'll get the aesthetically >>> pleasing intro.html file name without having to change the xml:id and >>> break xrefs to the section. However, if you have external links to >>> some-dumb-id.html from other documents, those links would obviously >>> break. >>> >>> Regardless of the publishing tool chain, when changing the names of >>> existing resources on the web, the best approach is to add 301 redirects >>> to avoid breaking bookmarks, links, and losing SEO karma. >>> >>> Regards, >>> David >>> >>> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140528/b76bd876/attachment.html> From mkassawara at gmail.com Wed May 28 14:22:04 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Wed, 28 May 2014 08:22:04 -0600 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CAD0KtVFD9RQa6Ct_dnHU8Ly60_+eYWWzoSN5tOx_dYZXO-42CA@mail.gmail.com> References: <CAD0KtVEm4pEwP2RVPah20SgjSruALXq9Cpq-imHsThnMrkbUug@mail.gmail.com> <CFAB57AE.2E379%diane.fleming@rackspace.com> <CAD0KtVFD9RQa6Ct_dnHU8Ly60_+eYWWzoSN5tOx_dYZXO-42CA@mail.gmail.com> Message-ID: <CABA+jQrTf-i=scx86HdT2q0qsU0GaNVsk6qcRq+0WjVvw0RiyQ@mail.gmail.com> +2 from me... thanks everyone! On Wed, May 28, 2014 at 8:20 AM, Anne Gentle <anne at openstack.org> wrote: > > > > On Wed, May 28, 2014 at 9:10 AM, Diane Fleming < > diane.fleming at rackspace.com> wrote: > >> That looks good. >> >> My only change would be that sections should be section_*, only because >> that's how most of them are named at the moment so it would save a lot of >> work to keep what we already have. >> > > Ha, oops, I should have known that, sorry. > > >> >> I have also used created other files for content sharing, such as >> itemized lists or tables. I usually prefix the file name with the object >> type in the file. >> >> > itemizedlist_service_list.xml (for example) >> table_server_status.xml >> >> > Makes sense. The table_prefix is very helpful. > > >> Oh, and for prefaces, I just use >> >> preface.xml >> >> > Ok, I'll note in the wiki page. Thanks! > > >> >> *Diane* >> *----------------------------------------------* >> Diane Fleming >> Software Developer II - US >> diane.fleming at rackspace.com >> Cell 512.323.6799 >> Office 512.874.1260 >> Skype drfleming0227 >> Google-plus diane.fleming at gmail.com >> >> From: Anne Gentle <anne at openstack.org> >> Date: Wednesday, May 28, 2014 9:04 AM >> >> To: Nick Chase <nchase at mirantis.com> >> Cc: Andreas Jaeger <aj at suse.com>, "openstack-docs at lists.openstack.org" < >> openstack-docs at lists.openstack.org> >> Subject: Re: [Openstack-docs] Conventions for filenames and >> chapter/section IDs >> >> Here's what I'll update in the Documentation/Conventions page if >> everyone agrees: >> >> For file names, use bk_ ch_ and sec_ at the beginning of the file name >> to indicate the type of file it is in the hierarchy of the build. For >> further organization, you can use subdirectories to organize the files by a >> particular grouping such as project or topic. >> >> For xml:id creation, follow these guidelines. >> - xml:id must be unique across a built deliverable, otherwise you get >> build errors >> - xml:id creates the HTML file name so it should be human-readable, not >> codified like the file name >> - xml:id should closely follow the actual title in the text, using >> dashes for spaces >> - xml:id creation should consider search and find-ability as well as >> human-readability >> >> I prefer not to document the use a processing instruction like <?dbhtml >> filename="name"> as that should be the rare exception. >> >> Thanks, >> Anne >> >> >> On Mon, May 26, 2014 at 11:13 AM, Nick Chase <nchase at mirantis.com> wrote: >> >>> My concern on this is that it raises a barrier to entry for >>> contributors. It's not intuitive. As a fix in an emergency, sure. But >>> I'd be concerned about building this out as the standard way we do things. >>> >>> ---- Nick >>> >>> >>> On Mon, May 26, 2014 at 11:43 AM, David Cramer < >>> david.cramer at rackspace.com> wrote: >>> >>>> On 5/26/14, 10:07 AM, Nick Chase wrote: >>>> > Plus my concern in changing Id values is breaking any references. >>>> >>>> You can reduce (but not eliminate) the impact of a file name change by >>>> changing the file names via a processing instruction: >>>> >>>> <section xml:id="some-dumb-id"><?dbhtml filename="intro.html"?>... >>>> >>>> If you use <?dbhtml filename="..."?> you'll get the aesthetically >>>> pleasing intro.html file name without having to change the xml:id and >>>> break xrefs to the section. However, if you have external links to >>>> some-dumb-id.html from other documents, those links would obviously >>>> break. >>>> >>>> Regardless of the publishing tool chain, when changing the names of >>>> existing resources on the web, the best approach is to add 301 redirects >>>> to avoid breaking bookmarks, links, and losing SEO karma. >>>> >>>> Regards, >>>> David >>>> >>>> >>> >>> _______________________________________________ >>> Openstack-docs mailing list >>> Openstack-docs at lists.openstack.org >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >>> >>> >> > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140528/ac336025/attachment-0001.html> From aj at suse.com Wed May 28 16:59:54 2014 From: aj at suse.com (Andreas Jaeger) Date: Wed, 28 May 2014 18:59:54 +0200 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <CAD0KtVEm4pEwP2RVPah20SgjSruALXq9Cpq-imHsThnMrkbUug@mail.gmail.com> References: <CABA+jQoKAoy8OUtNNf1bwUK3jCRrYqGRx22NpH_eUuATgD0fig@mail.gmail.com> <CFA8BDF2.2DFA0%diane.fleming@rackspace.com> <CA+p99Gnwea4hT=bo4=W4sTOG4jVXjbi8VrgO8UmkmDx9c_WxuA@mail.gmail.com> <911A41E5F7881A4C8DE8BE32135554A9A1CB8C21@ORD1EXD01.RACKSPACE.CORP> <CA+p99GnUAz0Z+CqzXutLAWkei51JjVp-H84AdYx+s6s_AHvPzA@mail.gmail.com> <CAD0KtVEm4pEwP2RVPah20SgjSruALXq9Cpq-imHsThnMrkbUug@mail.gmail.com> Message-ID: <5386160A.3040808@suse.com> On 05/28/2014 04:04 PM, Anne Gentle wrote: > Here's what I'll update in the Documentation/Conventions page if > everyone agrees: > > For file names, use bk_ ch_ and sec_ at the beginning of the file name > to indicate the type of file it is in the hierarchy of the build. For > further organization, you can use subdirectories to organize the files > by a particular grouping such as project or topic. Agreed (with using section as mentioned as followup) > For xml:id creation, follow these guidelines. > - xml:id must be unique across a built deliverable, otherwise you get > build errors > - xml:id creates the HTML file name so it should be human-readable, not > codified like the file name > - xml:id should closely follow the actual title in the text, using > dashes for spaces I normally use underscores for spaces. > - xml:id creation should consider search and find-ability as well as > human-readability > > I prefer not to document the use a processing instruction like <?dbhtml > filename="name"> as that should be the rare exception. > Agreed, thanks, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From anne at openstack.org Wed May 28 17:13:18 2014 From: anne at openstack.org (Anne Gentle) Date: Wed, 28 May 2014 12:13:18 -0500 Subject: [Openstack-docs] Conventions for filenames and chapter/section IDs In-Reply-To: <5386160A.3040808@suse.com> References: <CABA+jQoKAoy8OUtNNf1bwUK3jCRrYqGRx22NpH_eUuATgD0fig@mail.gmail.com> <CFA8BDF2.2DFA0%diane.fleming@rackspace.com> <CA+p99Gnwea4hT=bo4=W4sTOG4jVXjbi8VrgO8UmkmDx9c_WxuA@mail.gmail.com> <911A41E5F7881A4C8DE8BE32135554A9A1CB8C21@ORD1EXD01.RACKSPACE.CORP> <CA+p99GnUAz0Z+CqzXutLAWkei51JjVp-H84AdYx+s6s_AHvPzA@mail.gmail.com> <CAD0KtVEm4pEwP2RVPah20SgjSruALXq9Cpq-imHsThnMrkbUug@mail.gmail.com> <5386160A.3040808@suse.com> Message-ID: <CAD0KtVEffxEvV0Y3R8SorzXr558jptdzjbmAFyPp2CoEiaEYrA@mail.gmail.com> On Wed, May 28, 2014 at 11:59 AM, Andreas Jaeger <aj at suse.com> wrote: > On 05/28/2014 04:04 PM, Anne Gentle wrote: > > Here's what I'll update in the Documentation/Conventions page if > > everyone agrees: > > > > For file names, use bk_ ch_ and sec_ at the beginning of the file name > > to indicate the type of file it is in the hierarchy of the build. For > > further organization, you can use subdirectories to organize the files > > by a particular grouping such as project or topic. > > Agreed (with using section as mentioned as followup) > > > For xml:id creation, follow these guidelines. > > - xml:id must be unique across a built deliverable, otherwise you get > > build errors > > - xml:id creates the HTML file name so it should be human-readable, not > > codified like the file name > > - xml:id should closely follow the actual title in the text, using > > dashes for spaces > > I normally use underscores for spaces. > Ah, okay. I was thinking of Drupal/Wordpress convention and wondering if one is preferred over the other for search optimization, anyone know? > > > - xml:id creation should consider search and find-ability as well as > > human-readability > > > > I prefer not to document the use a processing instruction like <?dbhtml > > filename="name"> as that should be the rare exception. > > > > Agreed, thanks, > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140528/bc01b895/attachment.html> From mkassawara at gmail.com Wed May 28 23:55:11 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Wed, 28 May 2014 17:55:11 -0600 Subject: [Openstack-docs] Use of itemized lists in Ops Guide upgrade chapter Message-ID: <CABA+jQreES2pUZFZzUBgc0X0VUZeHy_C4FM+bW604DG=jx-eDA@mail.gmail.com> Can anyone tell me why the Ops Guide upgrade chapter uses itemized lists? If possible, I would like to use procedures to improve structure and readability. -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140528/6313678c/attachment.html> From anne at openstack.org Thu May 29 00:59:09 2014 From: anne at openstack.org (Anne Gentle) Date: Wed, 28 May 2014 19:59:09 -0500 Subject: [Openstack-docs] Use of itemized lists in Ops Guide upgrade chapter In-Reply-To: <CABA+jQreES2pUZFZzUBgc0X0VUZeHy_C4FM+bW604DG=jx-eDA@mail.gmail.com> References: <CABA+jQreES2pUZFZzUBgc0X0VUZeHy_C4FM+bW604DG=jx-eDA@mail.gmail.com> Message-ID: <CAD0KtVEszJn7cT_azosXV6AsoQ-eu+0_-HZPtypf8rAHcEJtkw@mail.gmail.com> Some of this is a judgement call due to the way it's written in sections with a step or two for each section. For the generalized listing of steps, those should remain lists. These sections could possibly be converted to procedures, but I'll try to explain why it might not be a good idea for each: - Perform a Backup (this is just two steps, First and Next so likely the judgement call was not to use procedure) - Update Configuration Files (there are a lot of "if" statements in this, I'm not sure how markup goes for optional steps, so likely they decided not to mark up with procedure since it's quite general) - Cleaning Up and Final Configuration File Updates (honestly, I can see why this also is not a procedure because it's not step-by-step, it's generalized guidance) Really, I think leave it alone, there is probably higher-value work to do than changing the markup there. Your testing has been super valuable and is the real value for that documentation. Anne On Wed, May 28, 2014 at 6:55 PM, Matt Kassawara <mkassawara at gmail.com>wrote: > Can anyone tell me why the Ops Guide upgrade chapter uses itemized lists? > If possible, I would like to use procedures to improve structure and > readability. > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140528/f16d87df/attachment.html> From mkassawara at gmail.com Thu May 29 01:06:30 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Wed, 28 May 2014 19:06:30 -0600 Subject: [Openstack-docs] Use of itemized lists in Ops Guide upgrade chapter In-Reply-To: <CAD0KtVEszJn7cT_azosXV6AsoQ-eu+0_-HZPtypf8rAHcEJtkw@mail.gmail.com> References: <CABA+jQreES2pUZFZzUBgc0X0VUZeHy_C4FM+bW604DG=jx-eDA@mail.gmail.com> <CAD0KtVEszJn7cT_azosXV6AsoQ-eu+0_-HZPtypf8rAHcEJtkw@mail.gmail.com> Message-ID: <CABA+jQrXGPyOOwZCcQjvqf3okrLD7QDgkQGFrxDZMCUx7t2kpA@mail.gmail.com> Alright... I'll upload my patch using the existing markup and see what happens during the review process. On Wed, May 28, 2014 at 6:59 PM, Anne Gentle <anne at openstack.org> wrote: > Some of this is a judgement call due to the way it's written in sections > with a step or two for each section. For the generalized listing of steps, > those should remain lists. > > These sections could possibly be converted to procedures, but I'll try to > explain why it might not be a good idea for each: > > - Perform a Backup (this is just two steps, First and Next so likely the > judgement call was not to use procedure) > - Update Configuration Files (there are a lot of "if" statements in this, > I'm not sure how markup goes for optional steps, so likely they decided not > to mark up with procedure since it's quite general) > - Cleaning Up and Final Configuration File Updates (honestly, I can see > why this also is not a procedure because it's not step-by-step, it's > generalized guidance) > > Really, I think leave it alone, there is probably higher-value work to do > than changing the markup there. Your testing has been super valuable and is > the real value for that documentation. > Anne > > > > > > On Wed, May 28, 2014 at 6:55 PM, Matt Kassawara <mkassawara at gmail.com>wrote: > >> Can anyone tell me why the Ops Guide upgrade chapter uses itemized lists? >> If possible, I would like to use procedures to improve structure and >> readability. >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140528/16dcd960/attachment.html> From tom at openstack.org Thu May 29 02:56:34 2014 From: tom at openstack.org (Tom Fifield) Date: Thu, 29 May 2014 10:56:34 +0800 Subject: [Openstack-docs] Training Guides becoming a project in its own right? Message-ID: <5386A1E2.80807@openstack.org> Hi, Sean Roberts, Stefano and I just had a very fruitful discussion regarding the training manuals project. We think that it's time to allow the the training guides to become a free-standing project of its own accord, and start attracting significantly more people around it. This will make it easier for contributors who just want to work on training to find the project, see lists of bugs and tasks relevant to them*, and also provide a clearer pathway toward becoming contributors, and eventually core reviewers. It will also enable the training guides project to have its own policies, and allow the repository to be used for investigation of training infrastructure, such as the recent forays into moodle for example. However, with every change such as this, there are drawbacks, and so we feel it's important to discuss these as well - and most importantly get your input. For example, while we can continue to re-use tools and content, this would mean a different review queue and repository - which could frustrate if you are working across both projects. What are your thoughts? Regards, Tom * as opposed to the 400 odd in the openstack-manuals tracker! From frans at meruvian.org Thu May 29 03:12:00 2014 From: frans at meruvian.org (Frans Thamura) Date: Thu, 29 May 2014 10:12:00 +0700 Subject: [Openstack-docs] Training Guides becoming a project in its own right? In-Reply-To: <5386A1E2.80807@openstack.org> References: <5386A1E2.80807@openstack.org> Message-ID: <CAOeeQyp9mz7wasNom516-GA0aVBgKXURTenk1WLO=CmscTzfDA@mail.gmail.com> +1 I love part of it. F On May 29, 2014 9:56 AM, "Tom Fifield" <tom at openstack.org> wrote: > Hi, > > Sean Roberts, Stefano and I just had a very fruitful discussion regarding > the training manuals project. > > We think that it's time to allow the the training guides to become a > free-standing project of its own accord, and start attracting significantly > more people around it. > > This will make it easier for contributors who just want to work on > training to find the project, see lists of bugs and tasks relevant to > them*, and also provide a clearer pathway toward becoming contributors, and > eventually core reviewers. > > It will also enable the training guides project to have its own policies, > and allow the repository to be used for investigation of training > infrastructure, such as the recent forays into moodle for example. > > However, with every change such as this, there are drawbacks, and so we > feel it's important to discuss these as well - and most importantly get > your input. > > For example, while we can continue to re-use tools and content, this would > mean a different review queue and repository - which could frustrate if you > are working across both projects. > > What are your thoughts? > > > Regards, > > > > Tom > > > * as opposed to the 400 odd in the openstack-manuals tracker! > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140529/073f7580/attachment.html> From gauvain.pocentek at objectif-libre.com Thu May 29 09:14:09 2014 From: gauvain.pocentek at objectif-libre.com (Gauvain Pocentek) Date: Thu, 29 May 2014 11:14:09 +0200 Subject: [Openstack-docs] [openstack-dev] [Heat][Documentation] Heat template documentation In-Reply-To: <0ffd733cc476e5b3ed39bb5be83bd5f7@objectif-libre.com> References: <CAD0KtVF6qnO4-Kd7ELxJZU53r7jtTSv7mCJG3ZVyJu-C+LxtYA@mail.gmail.com> <37903930f5456fa6f09066fe41cce960@objectif-libre.com> <CADb+p3RJ=cO0BxRsp7p=QiScS72dg5+ruz4WFZS9ZqyjE3sYcA@mail.gmail.com> <537BE872.3090509@redhat.com> <CAD0KtVHiqMgEq-A3ozq2ZVx3PtAZ=jwUnWHfa=pht5WXnLMHtA@mail.gmail.com> <537E6B94.1090806@redhat.com> <20140523101315.GA22280@t430slt.redhat.com> <537F2530.8010905@suse.com> <20140523111957.GB22280@t430slt.redhat.com> <CAD0KtVHP_=Og1uyL_p_k0+5nSk-8mJHFtOPbXqu-mO8R7QXg8Q@mail.gmail.com> <20140523134251.GC22280@t430slt.redhat.com> <CAD0KtVEyJmezeHhQqZXBwUwS9-cbafYp9sCcEp=ybiWuiKtUzw@mail.gmail.com> <f27ea5d694bbb2f800575c22266f0d39@objectif-libre.com> <53853639.2020506@redhat.com> <0ffd733cc476e5b3ed39bb5be83bd5f7@objectif-libre.com> Message-ID: <41416605e3d36f84d9013f029ba22765@objectif-libre.com> Le 2014-05-28 07:17, Gauvain Pocentek a ?crit?: > Le 2014-05-28 03:04, Steve Baker a ?crit?: >> On 28/05/14 03:15, Gauvain Pocentek wrote: >>> Le 2014-05-23 15:57, Anne Gentle a ?crit : >>>> On Fri, May 23, 2014 at 8:42 AM, Steven Hardy <shardy at redhat.com> >>>> wrote: >>>> >>>>> On Fri, May 23, 2014 at 08:09:06AM -0500, Anne Gentle wrote: >>>>>> On Fri, May 23, 2014 at 6:19 AM, Steven Hardy <shardy at redhat.com> >>>>>> wrote: >>>>>> >>>>>>> On Fri, May 23, 2014 at 12:38:40PM +0200, Andreas Jaeger wrote: >>>>>>>> On 05/23/2014 12:13 PM, Steven Hardy wrote: >>>>>>>>> [...] >>>>>>>>> I'll hold my hand up as one developer who tried to contribute >>>>>>>>> but ran >>>>>>> away >>>>>>>>> screaming due to all the XML-java-ness of the current process. >>>>>>>>> I don't think markup complexity is a major barrier to >>>>>>>>> contribution. >>>>>>> Needing >>>>>>>>> to use a closed source editor and download unfathomably huge >>>>>>>>> amounts of >>>>>>>>> java to build locally definitely are though IMO/IME. >>>>>>>> You do not need a closed sourced editor for XML - I'm using >>>>>>>> emacs >>>>>>>> and >>>>>>>> others in the team use vi for it. >>>>>>> Sure, maybe "need" was the wrong word to use, my apologies. >>>>>>> Regardless, >>>>>>> the docs refer to a closed source tool being "encouraged", which >>>>>>> immediately discouraged me when trying to figure out the >>>>>>> workflow. >>>>>>> I've tried editing XML in vim a few times, and although it's >>>>>>> obviously >>>>>>> possible, it's far less painful when I'm dealing with other more >>>>>>> human-friendly formats. >>>>>>> >>>>>>>> Yes, it downloads a lot Java once. We also now build the >>>>>>>> documents as >>>>>>>> part of the gate, so you can also check changes by clicking the >>>>>>>> "checkbuild" target, it will show you the converted books, >>>>>>> Sure, that's good, but my (and I'd guess many others) preference >>>>>>> is for >>>>>>> formats which can be easily built locally with only >>>>>>> distro-provided tools, >>>>>>> not a huge pile of third party java. >>>>>>> Not trying to start a format-advocacy argument here, just trying >>>>>>> to provide >>>>>>> a data-point that, if the success criteria is developer >>>>>>> participation in >>>>>>> the docs process, then the current toolchain is definitely a >>>>>>> barrier to >>>>>>> participation for some potential contributors. >>>>>>> >>>>>> Thanks for the discussions -- let's keep a tone of civility. >>>>>> Understand >>>>>> that doc writers have specific tools that work well for them. >>>>>> That >>>>>> said, we >>>>>> do want to collaborate more with our end users specifically. >>>>> My apologies if my remarks have been interpreted as uncivil, that >>>>> was >>>>> definitely not my intention. >>>> Oh no not at all, sorry -- my intent is that we are all staying >>>> civil >>>> and it's good. :) >>>> >>>> >>>>> The only point I really wanted to convey was +1 on trying out an >>>>> easier >>>>> markup, and thanks for bringing up the topic of a user orientated >>>>> orchestration guide - I would definitely like to contribute to the >>>>> effort. >>>> So we're still a little stuck on the tradeoffs -- with easier >>>> markup >>>> we lose some features. >>>> For other generated reference docs, we maintain a set of python >>>> scripts in openstack-doc-tools. Is it possible for someone to look >>>> into generating the Heat template reference information outside of >>>> Sphinx? >>> Yes, I can look into that. >>> The idea would be to generate some docbook from RST... So why not do >>> it for the whole to-be-written heat user guide in that case? >>> What I get from this thread is that 1) docbook is the best format to >>> use to generate a nice and feature-rich output, 2) developers don't >>> want to write docbook. Without being able to handle a different >>> format >>> developers will no contribute, which is bad because they want, and >>> we >>> want them to contribute :) >>> So my feeling is that we should work on the tools to convert RST (or >>> whatever format, but RST seems to be the "norm" for openstack >>> projects) to docbook, and generate our online documentation from >>> there. There are tools that can help us doing that, and I don't see >>> an >>> other solution that would make us move forward. >>> Anne, you talked about experimenting with the end user guide, and >>> after the discussion and the technical info brought by Doug, Steve >>> and >>> Steven, I now think it is worth trying. >>> >> In this vein, I enabled the sphinx xml builder in heat: >> https://review.openstack.org/#/c/95979/ >> And here is a sample of the output: >> http://paste.openstack.org/show/81811/ >> http://paste.openstack.org/show/81812/ >> This looks like it could be readily transformed into DocBook via XSL. > > http://ebellot.chez.com/dn2dbk/index.htm could be used as a starting > point. It generates docbook 4, but can probably be easily modified to > generate docbook 5, adapted to our conventions. The doc is in french, > if anyone's interested I can do a quick translation of the important > parts. The result of my tests: http://pocentek.net/~gauvain/heat-template-guide/content/ I used the XML generated by 'sphinx-build xml' as source, with this resources.py patch: https://review.openstack.org/96398 There are a few things manually setup (pom.xml, and the master structure of the docbook XML), but I think that they could be automated. I also used a few sed commands, mainly to handle xml IDs. It might be possible to handle this with xslt, but using sed was a faster solution. You can get the code: git clone http://pocentek.net/~gauvain/heat-template-guide/poc-rst2docbook There's room for improvement, and we should test more advanced RST markup, but I think that this solution could really work for the user guide. Gauvain From harry.sutton at hp.com Thu May 29 12:20:32 2014 From: harry.sutton at hp.com (Sutton, Harry (Converged Systems & Solutions ERT)) Date: Thu, 29 May 2014 08:20:32 -0400 Subject: [Openstack-docs] Training Guides becoming a project in its own right? In-Reply-To: <5386A1E2.80807@openstack.org> References: <5386A1E2.80807@openstack.org> Message-ID: <53872610.5090302@hp.com> I'm in favor of this - I'd like to get more involved in this effort, and having it as a separate project might simplify that process. /Harry On 05/28/2014 10:56 PM, Tom Fifield wrote: > Hi, > > Sean Roberts, Stefano and I just had a very fruitful discussion > regarding the training manuals project. > > We think that it's time to allow the the training guides to become a > free-standing project of its own accord, and start attracting > significantly more people around it. > > This will make it easier for contributors who just want to work on > training to find the project, see lists of bugs and tasks relevant to > them*, and also provide a clearer pathway toward becoming > contributors, and eventually core reviewers. > > It will also enable the training guides project to have its own > policies, and allow the repository to be used for investigation of > training infrastructure, such as the recent forays into moodle for > example. > > However, with every change such as this, there are drawbacks, and so > we feel it's important to discuss these as well - and most importantly > get your input. > > For example, while we can continue to re-use tools and content, this > would mean a different review queue and repository - which could > frustrate if you are working across both projects. > > What are your thoughts? > > > Regards, > > > > Tom > > > * as opposed to the 400 odd in the openstack-manuals tracker! > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- A non-text attachment was scrubbed... Name: smime.p7s Type: application/pkcs7-signature Size: 5079 bytes Desc: S/MIME Cryptographic Signature URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140529/e7249cf4/attachment.bin> From frans at meruvian.org Thu May 29 12:24:07 2014 From: frans at meruvian.org (Frans Thamura) Date: Thu, 29 May 2014 19:24:07 +0700 Subject: [Openstack-docs] Training Guides becoming a project in its own right? In-Reply-To: <53872610.5090302@hp.com> References: <5386A1E2.80807@openstack.org> <53872610.5090302@hp.com> Message-ID: <CAOeeQypOjk_LM-x9qctfqawvXaKmt0d6t9XMi_-n9ao0t2dP4g@mail.gmail.com> Any mechanism regarding this work? Esp.hard to get what going on in sfbay hackathon, which i am interest to create smiliar here in indonesia. The tutorial is amazing comperehensive, and we can see all distro tutorial pooled in openstack.org, this is awesome rather visiting every web of distro like ubuntu or centos . So when we can work? F On May 29, 2014 7:20 PM, "Sutton, Harry (Converged Systems & Solutions ERT)" <harry.sutton at hp.com> wrote: > I'm in favor of this - I'd like to get more involved in this effort, and > having it as a separate project might simplify that process. > > /Harry > > On 05/28/2014 10:56 PM, Tom Fifield wrote: > >> Hi, >> >> Sean Roberts, Stefano and I just had a very fruitful discussion regarding >> the training manuals project. >> >> We think that it's time to allow the the training guides to become a >> free-standing project of its own accord, and start attracting significantly >> more people around it. >> >> This will make it easier for contributors who just want to work on >> training to find the project, see lists of bugs and tasks relevant to >> them*, and also provide a clearer pathway toward becoming contributors, and >> eventually core reviewers. >> >> It will also enable the training guides project to have its own policies, >> and allow the repository to be used for investigation of training >> infrastructure, such as the recent forays into moodle for example. >> >> However, with every change such as this, there are drawbacks, and so we >> feel it's important to discuss these as well - and most importantly get >> your input. >> >> For example, while we can continue to re-use tools and content, this >> would mean a different review queue and repository - which could frustrate >> if you are working across both projects. >> >> What are your thoughts? >> >> >> Regards, >> >> >> >> Tom >> >> >> * as opposed to the 400 odd in the openstack-manuals tracker! >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140529/46e6a9da/attachment.html> From aj at suse.com Thu May 29 13:30:31 2014 From: aj at suse.com (Andreas Jaeger) Date: Thu, 29 May 2014 15:30:31 +0200 Subject: [Openstack-docs] Training Guides becoming a project in its own right? In-Reply-To: <5386A1E2.80807@openstack.org> References: <5386A1E2.80807@openstack.org> Message-ID: <53873677.1070107@suse.com> On 05/29/2014 04:56 AM, Tom Fifield wrote: > Hi, > > Sean Roberts, Stefano and I just had a very fruitful discussion > regarding the training manuals project. > > We think that it's time to allow the the training guides to become a > free-standing project of its own accord, and start attracting > significantly more people around it. > > This will make it easier for contributors who just want to work on > training to find the project, see lists of bugs and tasks relevant to > them*, and also provide a clearer pathway toward becoming contributors, > and eventually core reviewers. > > It will also enable the training guides project to have its own > policies, and allow the repository to be used for investigation of > training infrastructure, such as the recent forays into moodle for example. > > However, with every change such as this, there are drawbacks, and so we > feel it's important to discuss these as well - and most importantly get > your input. > > For example, while we can continue to re-use tools and content, this > would mean a different review queue and repository - which could > frustrate if you are working across both projects. > > What are your thoughts? I hope this will revive the training guide, it really needs a dedicated team that works on it to improve the quality and accuracy. I propose that the training guides team - even in its own project - works together with the documentation team to share tools and styles. There shouldn't be two different sets of conventions for writing... Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Thu May 29 13:32:47 2014 From: aj at suse.com (Andreas Jaeger) Date: Thu, 29 May 2014 15:32:47 +0200 Subject: [Openstack-docs] Training Guides becoming a project in its own right? In-Reply-To: <CAOeeQypOjk_LM-x9qctfqawvXaKmt0d6t9XMi_-n9ao0t2dP4g@mail.gmail.com> References: <5386A1E2.80807@openstack.org> <53872610.5090302@hp.com> <CAOeeQypOjk_LM-x9qctfqawvXaKmt0d6t9XMi_-n9ao0t2dP4g@mail.gmail.com> Message-ID: <538736FF.9060203@suse.com> On 05/29/2014 02:24 PM, Frans Thamura wrote: > Any mechanism regarding this work? > > Esp.hard to get what going on in sfbay hackathon, which i am interest to > create smiliar here in indonesia. > > The tutorial is amazing comperehensive, and we can see all distro > tutorial pooled in openstack.org <http://openstack.org>, this is awesome > rather visiting every web of distro like ubuntu or centos . > > So when we can work? You can already *today* work on the training guides, contribution is welcome! Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From aj at suse.com Thu May 29 14:49:51 2014 From: aj at suse.com (Andreas Jaeger) Date: Thu, 29 May 2014 16:49:51 +0200 Subject: [Openstack-docs] New localized doc web pages Message-ID: <5387490F.80304@suse.com> The API Quick Start has been translated to French, German, Japanese and Spanish! We now have German and French index pages: http://docs.openstack.org/de/ http://docs.openstack.org/fr/ (proposed - see https://review.openstack.org/96444) For all the guides that are not mentioned on a specific page, we now have a "secret" page which is not reachable from the main index pages: http://docs.openstack.org/draft-i18n-manuals.html It lists all the other guides that are currently built. That way translation teams can easily verify their manuals. If you like to move one of them to "official" pages, feel free to send a patch! Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From berendt at b1-systems.de Thu May 29 14:51:41 2014 From: berendt at b1-systems.de (Christian Berendt) Date: Thu, 29 May 2014 16:51:41 +0200 Subject: [Openstack-docs] Training Guides becoming a project in its own right? In-Reply-To: <5386A1E2.80807@openstack.org> References: <5386A1E2.80807@openstack.org> Message-ID: <5387497D.6030202@b1-systems.de> On 05/29/2014 04:56 AM, Tom Fifield wrote: > What are your thoughts? +1 It's a really good idea to move the training guide into a separate repository. Christian. -- Christian Berendt Cloud Computing Solution Architect Mail: berendt at b1-systems.de B1 Systems GmbH Osterfeldstra?e 7 / 85088 Vohburg / http://www.b1-systems.de GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 From anne at openstack.org Thu May 29 17:40:38 2014 From: anne at openstack.org (Anne Gentle) Date: Thu, 29 May 2014 12:40:38 -0500 Subject: [Openstack-docs] Training Guides becoming a project in its own right? In-Reply-To: <5386A1E2.80807@openstack.org> References: <5386A1E2.80807@openstack.org> Message-ID: <CAD0KtVGB2h0W1VzQ9wV4iH8ai5OfkzLwe4+J5pa+BkWxNq5Jig@mail.gmail.com> On Wed, May 28, 2014 at 9:56 PM, Tom Fifield <tom at openstack.org> wrote: > Hi, > > Sean Roberts, Stefano and I just had a very fruitful discussion regarding > the training manuals project. > Thanks you all for discussing. > > We think that it's time to allow the the training guides to become a > free-standing project of its own accord, and start attracting significantly > more people around it. > > This will make it easier for contributors who just want to work on > training to find the project, see lists of bugs and tasks relevant to > them*, and also provide a clearer pathway toward becoming contributors, and > eventually core reviewers. > > It will also enable the training guides project to have its own policies, > and allow the repository to be used for investigation of training > infrastructure, such as the recent forays into moodle for example. > > However, with every change such as this, there are drawbacks, and so we > feel it's important to discuss these as well - and most importantly get > your input. > > For example, while we can continue to re-use tools and content, this would > mean a different review queue and repository - which could frustrate if you > are working across both projects. > I hope the intention is to continue to use inclusion of known tested content from the various other OpenStack repos as needed. > > What are your thoughts? > Sounds great to me. Thanks all! Anne > > > Regards, > > > > Tom > > > * as opposed to the 400 odd in the openstack-manuals tracker! > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140529/5e2375bb/attachment.html> From anne at openstack.org Thu May 29 17:42:57 2014 From: anne at openstack.org (Anne Gentle) Date: Thu, 29 May 2014 12:42:57 -0500 Subject: [Openstack-docs] Anne out 5/30-6/9 Message-ID: <CAD0KtVHOmD7NMm=w_hP7q6rdGA3_fTdU=RiAXWsgtnPWOh5cHQ@mail.gmail.com> I'm taking vacation with the family and have no intentions of paying attention here for about a week. Don't throw any big parties without me. :) Thanks, Anne -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140529/9e6a0739/attachment.html> From mkassawara at gmail.com Thu May 29 17:47:53 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Thu, 29 May 2014 11:47:53 -0600 Subject: [Openstack-docs] Anne out 5/30-6/9 In-Reply-To: <CAD0KtVHOmD7NMm=w_hP7q6rdGA3_fTdU=RiAXWsgtnPWOh5cHQ@mail.gmail.com> References: <CAD0KtVHOmD7NMm=w_hP7q6rdGA3_fTdU=RiAXWsgtnPWOh5cHQ@mail.gmail.com> Message-ID: <CABA+jQpR_JFMUT1ncZVOuHzijpzwYLGFAs-gon+wap41ZUXmXw@mail.gmail.com> We'll just +2 and approve every patch while you're out. Hope you have a great time! On Thu, May 29, 2014 at 11:42 AM, Anne Gentle <anne at openstack.org> wrote: > I'm taking vacation with the family and have no intentions of paying > attention here for about a week. Don't throw any big parties without me. :) > Thanks, > Anne > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140529/ec0d1f78/attachment.html> From aj at suse.com Thu May 29 19:12:22 2014 From: aj at suse.com (Andreas Jaeger) Date: Thu, 29 May 2014 21:12:22 +0200 Subject: [Openstack-docs] Training Guide freeze? Message-ID: <53878696.80405@suse.com> Tom, seeing your patch https://review.openstack.org/#/c/96334/4, I propose that we freeze the training guide for its transition now. This means we're not changing any files below doc/training-guides. Correct? Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From openstack at lanabrindley.com Thu May 29 23:56:45 2014 From: openstack at lanabrindley.com (Lana Brindley) Date: Fri, 30 May 2014 09:56:45 +1000 Subject: [Openstack-docs] Anne out 5/30-6/9 In-Reply-To: <CABA+jQpR_JFMUT1ncZVOuHzijpzwYLGFAs-gon+wap41ZUXmXw@mail.gmail.com> References: <CAD0KtVHOmD7NMm=w_hP7q6rdGA3_fTdU=RiAXWsgtnPWOh5cHQ@mail.gmail.com> <CABA+jQpR_JFMUT1ncZVOuHzijpzwYLGFAs-gon+wap41ZUXmXw@mail.gmail.com> Message-ID: <5387C93D.6030903@lanabrindley.com> It's a +2 party! Have a great vacation, Anne :) L On 30/05/14 03:47, Matt Kassawara wrote: > We'll just +2 and approve every patch while you're out. Hope you have a > great time! > > > On Thu, May 29, 2014 at 11:42 AM, Anne Gentle <anne at openstack.org > <mailto:anne at openstack.org>> wrote: > > I'm taking vacation with the family and have no intentions of paying > attention here for about a week. Don't throw any big parties without > me. :) > Thanks, > Anne > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > <mailto:Openstack-docs at lists.openstack.org> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > > > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -- Lana Brindley Technical Writer Rackspace Cloud Builders Australia http://lanabrindley.com From diane.fleming at RACKSPACE.COM Fri May 30 00:49:45 2014 From: diane.fleming at RACKSPACE.COM (Diane Fleming) Date: Fri, 30 May 2014 00:49:45 +0000 Subject: [Openstack-docs] Anne out 5/30-6/9 In-Reply-To: <5387C93D.6030903@lanabrindley.com> References: <CAD0KtVHOmD7NMm=w_hP7q6rdGA3_fTdU=RiAXWsgtnPWOh5cHQ@mail.gmail.com> <CABA+jQpR_JFMUT1ncZVOuHzijpzwYLGFAs-gon+wap41ZUXmXw@mail.gmail.com>, <5387C93D.6030903@lanabrindley.com> Message-ID: <24804B9A-A028-4FCF-8001-84BE6EAF5F3B@RACKSPACE.COM> 2 plus 2 is 4, i've heard. Ann, leave your computer at home!! Sent from my iPhone > On May 29, 2014, at 6:58 PM, "Lana Brindley" <openstack at lanabrindley.com> wrote: > > It's a +2 party! > > Have a great vacation, Anne :) > > L > >> On 30/05/14 03:47, Matt Kassawara wrote: >> We'll just +2 and approve every patch while you're out. Hope you have a >> great time! >> >> >> On Thu, May 29, 2014 at 11:42 AM, Anne Gentle <anne at openstack.org >> <mailto:anne at openstack.org>> wrote: >> >> I'm taking vacation with the family and have no intentions of paying >> attention here for about a week. Don't throw any big parties without >> me. :) >> Thanks, >> Anne >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> <mailto:Openstack-docs at lists.openstack.org> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs >> >> >> >> >> _______________________________________________ >> Openstack-docs mailing list >> Openstack-docs at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > > -- > Lana Brindley > Technical Writer > Rackspace Cloud Builders Australia > http://lanabrindley.com > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs From tom at openstack.org Fri May 30 01:14:34 2014 From: tom at openstack.org (Tom Fifield) Date: Fri, 30 May 2014 09:14:34 +0800 Subject: [Openstack-docs] Training Guides becoming a project in its own right? In-Reply-To: <CAD0KtVGB2h0W1VzQ9wV4iH8ai5OfkzLwe4+J5pa+BkWxNq5Jig@mail.gmail.com> References: <5386A1E2.80807@openstack.org> <CAD0KtVGB2h0W1VzQ9wV4iH8ai5OfkzLwe4+J5pa+BkWxNq5Jig@mail.gmail.com> Message-ID: <5387DB7A.5070502@openstack.org> On 30/05/14 01:40, Anne Gentle wrote: > > > > On Wed, May 28, 2014 at 9:56 PM, Tom Fifield <tom at openstack.org > <mailto:tom at openstack.org>> wrote: > > Hi, > > Sean Roberts, Stefano and I just had a very fruitful discussion > regarding the training manuals project. > > > Thanks you all for discussing. > > > We think that it's time to allow the the training guides to become a > free-standing project of its own accord, and start attracting > significantly more people around it. > > > This will make it easier for contributors who just want to work on > training to find the project, see lists of bugs and tasks relevant > to them*, and also provide a clearer pathway toward becoming > contributors, and eventually core reviewers. > > It will also enable the training guides project to have its own > policies, and allow the repository to be used for investigation of > training infrastructure, such as the recent forays into moodle for > example. > > However, with every change such as this, there are drawbacks, and so > we feel it's important to discuss these as well - and most > importantly get your input. > > For example, while we can continue to re-use tools and content, this > would mean a different review queue and repository - which could > frustrate if you are working across both projects. > > > I hope the intention is to continue to use inclusion of known tested > content from the various other OpenStack repos as needed. Yup, that's the case. > > What are your thoughts? > > > Sounds great to me. Thanks all! > Anne > > > > Regards, > > > > Tom > > > * as opposed to the 400 odd in the openstack-manuals tracker! > > _________________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.__openstack.org > <mailto:Openstack-docs at lists.openstack.org> > http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs > <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs> > > From mkassawara at gmail.com Fri May 30 01:31:08 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Thu, 29 May 2014 19:31:08 -0600 Subject: [Openstack-docs] Anne out 5/30-6/9 In-Reply-To: <24804B9A-A028-4FCF-8001-84BE6EAF5F3B@RACKSPACE.COM> References: <CAD0KtVHOmD7NMm=w_hP7q6rdGA3_fTdU=RiAXWsgtnPWOh5cHQ@mail.gmail.com> <CABA+jQpR_JFMUT1ncZVOuHzijpzwYLGFAs-gon+wap41ZUXmXw@mail.gmail.com> <5387C93D.6030903@lanabrindley.com> <24804B9A-A028-4FCF-8001-84BE6EAF5F3B@RACKSPACE.COM> Message-ID: <CABA+jQo8Pz=n_eDftk2zdDNzuEdzALLoO3WnmJEuTLgnZEdrqA@mail.gmail.com> Or 2 plus 2 is 5 for extremely high values of 2. :) On Thu, May 29, 2014 at 6:49 PM, Diane Fleming <diane.fleming at rackspace.com> wrote: > 2 plus 2 is 4, i've heard. Ann, leave your computer at home!! > > Sent from my iPhone > > > On May 29, 2014, at 6:58 PM, "Lana Brindley" <openstack at lanabrindley.com> > wrote: > > > > It's a +2 party! > > > > Have a great vacation, Anne :) > > > > L > > > >> On 30/05/14 03:47, Matt Kassawara wrote: > >> We'll just +2 and approve every patch while you're out. Hope you have a > >> great time! > >> > >> > >> On Thu, May 29, 2014 at 11:42 AM, Anne Gentle <anne at openstack.org > >> <mailto:anne at openstack.org>> wrote: > >> > >> I'm taking vacation with the family and have no intentions of paying > >> attention here for about a week. Don't throw any big parties without > >> me. :) > >> Thanks, > >> Anne > >> > >> _______________________________________________ > >> Openstack-docs mailing list > >> Openstack-docs at lists.openstack.org > >> <mailto:Openstack-docs at lists.openstack.org> > >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > >> > >> > >> > >> > >> _______________________________________________ > >> Openstack-docs mailing list > >> Openstack-docs at lists.openstack.org > >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > > > > > -- > > Lana Brindley > > Technical Writer > > Rackspace Cloud Builders Australia > > http://lanabrindley.com > > > > _______________________________________________ > > Openstack-docs mailing list > > Openstack-docs at lists.openstack.org > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > _______________________________________________ > Openstack-docs mailing list > Openstack-docs at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140529/c1136058/attachment-0001.html> From guoyingc at cn.ibm.com Fri May 30 02:22:49 2014 From: guoyingc at cn.ibm.com (Ying Chun Guo) Date: Fri, 30 May 2014 10:22:49 +0800 Subject: [Openstack-docs] [Openstack-i18n] New localized doc web pages In-Reply-To: <5387490F.80304@suse.com> References: <5387490F.80304@suse.com> Message-ID: <OFD71DFDDC.1852867E-ON48257CE8.000CFFBC-48257CE8.000D2E66@cn.ibm.com> Thanks, Andreas. How to add documents to the secret page then? Best regards Ying Chun Guo (Daisy) Andreas Jaeger <aj at suse.com> wrote on 2014/05/29 22:49:51: > Andreas Jaeger <aj at suse.com> > 2014/05/29 22:49 > > To > > "openstack-docs at lists.openstack.org" <openstack- > docs at lists.openstack.org>, "openstack-i18n at lists.openstack.org" > <openstack-i18n at lists.openstack.org>, > > cc > > Subject > > [Openstack-i18n] New localized doc web pages > > The API Quick Start has been translated to French, German, Japanese and > Spanish! > > We now have German and French index pages: > http://docs.openstack.org/de/ > http://docs.openstack.org/fr/ (proposed - see > https://review.openstack.org/96444) > > For all the guides that are not mentioned on a specific page, we now > have a "secret" page which is not reachable from the main index pages: > > http://docs.openstack.org/draft-i18n-manuals.html > > It lists all the other guides that are currently built. That way > translation teams can easily verify their manuals. > If you like to move one of them to "official" pages, feel free to send a > patch! > > Andreas > -- > Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi > SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany > GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) > GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 > > _______________________________________________ > Openstack-i18n mailing list > Openstack-i18n at lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140530/31d1fce7/attachment.html> From aj at suse.com Fri May 30 04:21:06 2014 From: aj at suse.com (Andreas Jaeger) Date: Fri, 30 May 2014 06:21:06 +0200 Subject: [Openstack-docs] [Openstack-i18n] New localized doc web pages In-Reply-To: <OFD71DFDDC.1852867E-ON48257CE8.000CFFBC-48257CE8.000D2E66@cn.ibm.com> References: <5387490F.80304@suse.com> <OFD71DFDDC.1852867E-ON48257CE8.000CFFBC-48257CE8.000D2E66@cn.ibm.com> Message-ID: <53880732.20404@suse.com> On 05/30/2014 04:22 AM, Ying Chun Guo wrote: > Thanks, Andreas. > How to add documents to the secret page then? Like this: https://review.openstack.org/96517 We publish it like any other page, it's just not reachable from the main entry points, Andreas > Best regards > Ying Chun Guo (Daisy) > > > Andreas Jaeger <aj at suse.com> wrote on 2014/05/29 22:49:51: > >> Andreas Jaeger <aj at suse.com> >> 2014/05/29 22:49 >> >> To >> >> "openstack-docs at lists.openstack.org" <openstack- >> docs at lists.openstack.org>, "openstack-i18n at lists.openstack.org" >> <openstack-i18n at lists.openstack.org>, >> >> cc >> >> Subject >> >> [Openstack-i18n] New localized doc web pages >> >> The API Quick Start has been translated to French, German, Japanese and >> Spanish! >> >> We now have German and French index pages: >> http://docs.openstack.org/de/ >> http://docs.openstack.org/fr/ (proposed - see >> https://review.openstack.org/96444) >> >> For all the guides that are not mentioned on a specific page, we now >> have a "secret" page which is not reachable from the main index pages: >> >> http://docs.openstack.org/draft-i18n-manuals.html >> >> It lists all the other guides that are currently built. That way >> translation teams can easily verify their manuals. >> If you like to move one of them to "official" pages, feel free to send a >> patch! >> >> Andreas >> -- >> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany >> GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 >> >> _______________________________________________ >> Openstack-i18n mailing list >> Openstack-i18n at lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n >> > -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 From mkassawara at gmail.com Fri May 30 14:44:34 2014 From: mkassawara at gmail.com (Matt Kassawara) Date: Fri, 30 May 2014 08:44:34 -0600 Subject: [Openstack-docs] Patch for automated Debian installations Message-ID: <CABA+jQoRDAqgKRj7xKHUFi-xKODX_gL7a-HNgcG8-sJ3epNaUg@mail.gmail.com> I saw this patch for automated Debian installations: https://review.openstack.org/#/c/96695/ I'm concerned that it doesn't agree with the purpose of the installation guide and would like to discuss it further. -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140530/c1e7b60e/attachment.html> From sgordon at redhat.com Fri May 30 15:47:16 2014 From: sgordon at redhat.com (Steve Gordon) Date: Fri, 30 May 2014 11:47:16 -0400 (EDT) Subject: [Openstack-docs] Patch for automated Debian installations In-Reply-To: <CABA+jQoRDAqgKRj7xKHUFi-xKODX_gL7a-HNgcG8-sJ3epNaUg@mail.gmail.com> References: <CABA+jQoRDAqgKRj7xKHUFi-xKODX_gL7a-HNgcG8-sJ3epNaUg@mail.gmail.com> Message-ID: <1954988965.23132074.1401464836421.JavaMail.zimbra@redhat.com> ----- Original Message ----- > From: "Matt Kassawara" <mkassawara at gmail.com> > To: openstack-docs at lists.openstack.org > Sent: Friday, May 30, 2014 10:44:34 AM > Subject: [Openstack-docs] Patch for automated Debian installations > > I saw this patch for automated Debian installations: > > https://review.openstack.org/#/c/96695/ > > I'm concerned that it doesn't agree with the purpose of the installation > guide and would like to discuss it further. Thanks for highlighting this Matt, I am -2 on this submission based on my understanding of our current direction - which appears to match yours - and have recorded my reasoning in the review as follows: "If we were to include this we would also need to open it up to the other distro's automated deployment tools such as PackStack, Crowbar, JuJu, FUEL, Foreman, etc. We have previously decided against this as the aim of the installation guide on docs.o.o is to aid users in learning about the inner workings of OpenStack as they deploy it - not to provide an "easy button". Individual distributions of course can and do maintain their own documentation of the "easy button" elsewhere. An acceptable middle ground might be to provide a section for linking to, but explicitly not endorsing, these external resources." I would add that I am not necessarily in favour of the middle ground I suggest above but thought I would put it out there. Thanks, Steve