Re: [openstack-dev] [Openstack-docs] Contributing to docs without Docbook -- YES you can!
On Fri, Oct 3, 2014 at 3:07 PM, Stefano Maffulli stef...@openstack.org wrote: 4. Send e-mail to reviewers network...@openstacknow.com. Why not use the docs mailing list or other facilities on @openstack.org? We've now switched over to use the [networking] topic on the openstack-docs list. So anybody who's interested in following the discussions, please feel free to join us. Thanks! - Nick ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Openstack-docs] Contributing to docs without Docbook -- YES you can!
Bonjour Gauvain, Un gros bravo pour cette documentation sur Heat qui est très complète. Est-ce que par hasard vous auriez déjà une version française ? ;) Best, F. -Message d'origine- De : Gauvain Pocentek [mailto:gauvain.pocen...@objectif-libre.com] Envoyé : lundi 6 octobre 2014 07:06 À : Tom Fifield Cc : OpenStack Development Mailing List (not for usage questions); openstack-d...@lists.openstack.org Objet : Re: [openstack-dev] [Openstack-docs] Contributing to docs without Docbook -- YES you can! Le 2014-10-06 05:26, Tom Fifield a écrit : On 04/10/14 04:03, Nick Chase wrote: On Fri, Oct 3, 2014 at 3:07 PM, Stefano Maffulli stef...@openstack.org mailto:stef...@openstack.org wrote: 1. Pick an existing topic or create a new topic. For new topics, we're primarily interested in deployment scenarios. 2. Develop content (text and/or diagrams) in a format that supports at least basic markup (e.g., titles, paragraphs, lists, etc.). 3. Provide a link to the content (e.g., gist on github.com http://github.com, wiki page, blog post, etc.) under the associated topic. Points 1-3 seem to be oriented at removing Launchpad from the equation. Is that all there is? I guess it makes sense to remove obstacles, although editing the wiki (since it requires a launchpad account anyway) may not be the best way to track progress and see assignments. No, really, the main change is in step 5. Launchpad isn't the problem, as far as we can tell; Docbook is. Hi Nick, As best I can tell - 'step 5' has been in place for at least the last few summits at least, so this is not a change :) We have had a policy where anyone can dump text in bug reports and we'll wrangle it. This has been popular, see eg Marco Cossoni's contributions, but in my opinion not widely enough communicated - so thanks for your efforts. We actually have another way to work with developers, although it's been only available for the new HOT guide. This guide is temporary, it will become a part of the user guide. The interesting point is that it's written in RST, and uses gerrit for reviews. So far we've had 2 core members of the heat team contributing content, and this content has been reviewed by other members of the team. The devs patches focused on content, not on the form of the content. I suggested to accept the patches rapidly - as long as they're technically correct - and to rework them later (what I've started to do a couple days ago). The fact that we're using gerrit and that the developers review each other work makes me more comfortable with the quality of the content. I'd really like to see this process extended to a larger part of the documentation, although this might not be needed everywhere. I had this workflow in mind: * a dev sends a review to a temporary repo * other devs can validate the information, and give their +1 when the patch is ready * a doc reviewer either requests more technical detail, or gives his +2/accept * the doc team reworks the patch and integrates it to the doc repository I really think that the process worked for the HOT guide, and I'm convinced that it could work for other parts of the doc (Cinder and Neutron drivers doc for instance). As a side note, we have a tool that converts RST to docbook. The hot guide is automatically built using this tool (http://docs.openstack.org/hot-guide/content/hot_guide_hot-guide.html). Gauvain ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Openstack-docs] Contributing to docs without Docbook -- YES you can!
Hi François, I guess this mail was directed to me personally but I'll answer here, this might be useful for the translation teams. There's no existing translation for the HOT guide yet, and I'm not sure that now is the best time to get started. The (temporary standalone) HOT guide will end up as a user guide section, in docbook (not RST). I'm currently rewriting some sections and more content will be added soon, so expect lots of modifications. As soon as it's ready to be officially published in the user guide, the translation tools will import the docbook strings in transifex (that's the plan at least). Gauvain Le 2014-10-06 16:05, François Bureau a écrit : Bonjour Gauvain, Un gros bravo pour cette documentation sur Heat qui est très complète. Est-ce que par hasard vous auriez déjà une version française ? ;) Best, F. -Message d'origine- De : Gauvain Pocentek [mailto:gauvain.pocen...@objectif-libre.com] Envoyé : lundi 6 octobre 2014 07:06 À : Tom Fifield Cc : OpenStack Development Mailing List (not for usage questions); openstack-d...@lists.openstack.org Objet : Re: [openstack-dev] [Openstack-docs] Contributing to docs without Docbook -- YES you can! Le 2014-10-06 05:26, Tom Fifield a écrit : On 04/10/14 04:03, Nick Chase wrote: On Fri, Oct 3, 2014 at 3:07 PM, Stefano Maffulli stef...@openstack.org mailto:stef...@openstack.org wrote: 1. Pick an existing topic or create a new topic. For new topics, we're primarily interested in deployment scenarios. 2. Develop content (text and/or diagrams) in a format that supports at least basic markup (e.g., titles, paragraphs, lists, etc.). 3. Provide a link to the content (e.g., gist on github.com http://github.com, wiki page, blog post, etc.) under the associated topic. Points 1-3 seem to be oriented at removing Launchpad from the equation. Is that all there is? I guess it makes sense to remove obstacles, although editing the wiki (since it requires a launchpad account anyway) may not be the best way to track progress and see assignments. No, really, the main change is in step 5. Launchpad isn't the problem, as far as we can tell; Docbook is. Hi Nick, As best I can tell - 'step 5' has been in place for at least the last few summits at least, so this is not a change :) We have had a policy where anyone can dump text in bug reports and we'll wrangle it. This has been popular, see eg Marco Cossoni's contributions, but in my opinion not widely enough communicated - so thanks for your efforts. We actually have another way to work with developers, although it's been only available for the new HOT guide. This guide is temporary, it will become a part of the user guide. The interesting point is that it's written in RST, and uses gerrit for reviews. So far we've had 2 core members of the heat team contributing content, and this content has been reviewed by other members of the team. The devs patches focused on content, not on the form of the content. I suggested to accept the patches rapidly - as long as they're technically correct - and to rework them later (what I've started to do a couple days ago). The fact that we're using gerrit and that the developers review each other work makes me more comfortable with the quality of the content. I'd really like to see this process extended to a larger part of the documentation, although this might not be needed everywhere. I had this workflow in mind: * a dev sends a review to a temporary repo * other devs can validate the information, and give their +1 when the patch is ready * a doc reviewer either requests more technical detail, or gives his +2/accept * the doc team reworks the patch and integrates it to the doc repository I really think that the process worked for the HOT guide, and I'm convinced that it could work for other parts of the doc (Cinder and Neutron drivers doc for instance). As a side note, we have a tool that converts RST to docbook. The hot guide is automatically built using this tool (http://docs.openstack.org/hot-guide/content/hot_guide_hot-guide.html). Gauvain ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Openstack-docs] Contributing to docs without Docbook -- YES you can!
On 10/06/2014 04:56 PM, Gauvain Pocentek wrote:
Hi François,
I guess this mail was directed to me personally but I'll answer here,
this might be useful for the translation teams.
There's no existing translation for the HOT guide yet, and I'm not sure
that now is the best time to get started. The (temporary standalone) HOT
guide will end up as a user guide section, in docbook (not RST). I'm
currently rewriting some sections and more content will be added soon,
so expect lots of modifications. As soon as it's ready to be officially
published in the user guide, the translation tools will import the
docbook strings in transifex (that's the plan at least).
Translations have been setup for the guide - like for all other
OpenStack manuals as our toolchains needs it.
Still, let's wait with translations,
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-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Openstack-docs] Contributing to docs without Docbook -- YES you can!
On 04/10/14 04:03, Nick Chase wrote: On Fri, Oct 3, 2014 at 3:07 PM, Stefano Maffulli stef...@openstack.org mailto:stef...@openstack.org wrote: 1. Pick an existing topic or create a new topic. For new topics, we're primarily interested in deployment scenarios. 2. Develop content (text and/or diagrams) in a format that supports at least basic markup (e.g., titles, paragraphs, lists, etc.). 3. Provide a link to the content (e.g., gist on github.com http://github.com, wiki page, blog post, etc.) under the associated topic. Points 1-3 seem to be oriented at removing Launchpad from the equation. Is that all there is? I guess it makes sense to remove obstacles, although editing the wiki (since it requires a launchpad account anyway) may not be the best way to track progress and see assignments. No, really, the main change is in step 5. Launchpad isn't the problem, as far as we can tell; Docbook is. Hi Nick, As best I can tell - 'step 5' has been in place for at least the last few summits at least, so this is not a change :) We have had a policy where anyone can dump text in bug reports and we'll wrangle it. This has been popular, see eg Marco Cossoni's contributions, but in my opinion not widely enough communicated - so thanks for your efforts. 4. Send e-mail to reviewers network...@openstacknow.com mailto:network...@openstacknow.com. Why not use the docs mailing list or other facilities on @openstack.org http://openstack.org? Who is responding to that address? If someone want to provide us a list on @openstack.org http://openstack.org, that'd be awesome. I set up this address because I control the forwarding and could do it immediately without having to ask for anyone's approval. :) People on the alias are myself, Edgar Magana, Matt Kasawara, Phil Hopkins, Anne Gentle, and Elke Vorheis. I find it quite odd that the larger team is being excluded from this effort. Why would it need a separate mailing list? Regards, Tom ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Openstack-docs] Contributing to docs without Docbook -- YES you can!
On Sun, Oct 5, 2014 at 11:26 PM, Tom Fifield t...@openstack.org wrote: On 04/10/14 04:03, Nick Chase wrote: On Fri, Oct 3, 2014 at 3:07 PM, Stefano Maffulli stef...@openstack.org mailto:stef...@openstack.org wrote: 1. Pick an existing topic or create a new topic. For new topics, we're primarily interested in deployment scenarios. 2. Develop content (text and/or diagrams) in a format that supports at least basic markup (e.g., titles, paragraphs, lists, etc.). 3. Provide a link to the content (e.g., gist on github.com http://github.com, wiki page, blog post, etc.) under the associated topic. Points 1-3 seem to be oriented at removing Launchpad from the equation. Is that all there is? I guess it makes sense to remove obstacles, although editing the wiki (since it requires a launchpad account anyway) may not be the best way to track progress and see assignments. No, really, the main change is in step 5. Launchpad isn't the problem, as far as we can tell; Docbook is. Hi Nick, As best I can tell - 'step 5' has been in place for at least the last few summits at least, so this is not a change :) We have had a policy where anyone can dump text in bug reports and we'll wrangle it. This has been popular, see eg Marco Cossoni's contributions, but in my opinion not widely enough communicated - so thanks for your efforts. Right, again, it's fantastic that people can dump text in bug reports, and yes, it's probably not well known. We're just trying to sort of widen out what people are sending from a few paragraphs to entire topics. But hey, the general idea is the same. We're all trying to get to the same point. Obviously there's something about the current process that's not working as well as it could. This experiment is about trying to figure out what. If all we're changing is moving the contribution point from a bug report to a wiki, then great; having just one changed variable among control variables is good science. 4. Send e-mail to reviewers network...@openstacknow.com mailto:network...@openstacknow.com. Why not use the docs mailing list or other facilities on @openstack.org http://openstack.org? Who is responding to that address? If someone want to provide us a list on @openstack.org http://openstack.org, that'd be awesome. I set up this address because I control the forwarding and could do it immediately without having to ask for anyone's approval. :) People on the alias are myself, Edgar Magana, Matt Kasawara, Phil Hopkins, Anne Gentle, and Elke Vorheis. I find it quite odd that the larger team is being excluded from this effort. Why would it need a separate mailing list? We haven't intentionally excluded anybody; we were just keeping it small both to keep it a focused effort -- this way we could more easily hash things out without anybody stepping on anybody else -- and so that we weren't essentially volunteering people against their will. :) But we can easily change it over to the main docs list. Nick ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Openstack-docs] Contributing to docs without Docbook -- YES you can!
On 06/10/14 11:38, Nick Chase wrote: On Sun, Oct 5, 2014 at 11:26 PM, Tom Fifield t...@openstack.org mailto:t...@openstack.org wrote: On 04/10/14 04:03, Nick Chase wrote: On Fri, Oct 3, 2014 at 3:07 PM, Stefano Maffulli stef...@openstack.org mailto:stef...@openstack.org mailto:stef...@openstack.org mailto:stef...@openstack.org wrote: 1. Pick an existing topic or create a new topic. For new topics, we're primarily interested in deployment scenarios. 2. Develop content (text and/or diagrams) in a format that supports at least basic markup (e.g., titles, paragraphs, lists, etc.). 3. Provide a link to the content (e.g., gist on github.com http://github.com http://github.com, wiki page, blog post, etc.) under the associated topic. Points 1-3 seem to be oriented at removing Launchpad from the equation. Is that all there is? I guess it makes sense to remove obstacles, although editing the wiki (since it requires a launchpad account anyway) may not be the best way to track progress and see assignments. No, really, the main change is in step 5. Launchpad isn't the problem, as far as we can tell; Docbook is. Hi Nick, As best I can tell - 'step 5' has been in place for at least the last few summits at least, so this is not a change :) We have had a policy where anyone can dump text in bug reports and we'll wrangle it. This has been popular, see eg Marco Cossoni's contributions, but in my opinion not widely enough communicated - so thanks for your efforts. Right, again, it's fantastic that people can dump text in bug reports, and yes, it's probably not well known. We're just trying to sort of widen out what people are sending from a few paragraphs to entire topics. But hey, the general idea is the same. We're all trying to get to the same point. Obviously there's something about the current process that's not working as well as it could. This experiment is about trying to figure out what. If all we're changing is moving the contribution point from a bug report to a wiki, then great; having just one changed variable among control variables is good science. 4. Send e-mail to reviewers network...@openstacknow.com mailto:network...@openstacknow.com mailto:network...@openstacknow.com mailto:network...@openstacknow.com. Why not use the docs mailing list or other facilities on @openstack.org http://openstack.org http://openstack.org? Who is responding to that address? If someone want to provide us a list on @openstack.org http://openstack.org http://openstack.org, that'd be awesome. I set up this address because I control the forwarding and could do it immediately without having to ask for anyone's approval. :) People on the alias are myself, Edgar Magana, Matt Kasawara, Phil Hopkins, Anne Gentle, and Elke Vorheis. I find it quite odd that the larger team is being excluded from this effort. Why would it need a separate mailing list? We haven't intentionally excluded anybody; we were just keeping it small both to keep it a focused effort -- this way we could more easily hash things out without anybody stepping on anybody else -- and so that we weren't essentially volunteering people against their will. :) But we can easily change it over to the main docs list. Yup - I think that would be more in the spirit of our Open Development core principle and I would encourage you to do so. Regards, Tom ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Openstack-docs] Contributing to docs without Docbook -- YES you can!
Le 2014-10-06 05:26, Tom Fifield a écrit : On 04/10/14 04:03, Nick Chase wrote: On Fri, Oct 3, 2014 at 3:07 PM, Stefano Maffulli stef...@openstack.org mailto:stef...@openstack.org wrote: 1. Pick an existing topic or create a new topic. For new topics, we're primarily interested in deployment scenarios. 2. Develop content (text and/or diagrams) in a format that supports at least basic markup (e.g., titles, paragraphs, lists, etc.). 3. Provide a link to the content (e.g., gist on github.com http://github.com, wiki page, blog post, etc.) under the associated topic. Points 1-3 seem to be oriented at removing Launchpad from the equation. Is that all there is? I guess it makes sense to remove obstacles, although editing the wiki (since it requires a launchpad account anyway) may not be the best way to track progress and see assignments. No, really, the main change is in step 5. Launchpad isn't the problem, as far as we can tell; Docbook is. Hi Nick, As best I can tell - 'step 5' has been in place for at least the last few summits at least, so this is not a change :) We have had a policy where anyone can dump text in bug reports and we'll wrangle it. This has been popular, see eg Marco Cossoni's contributions, but in my opinion not widely enough communicated - so thanks for your efforts. We actually have another way to work with developers, although it's been only available for the new HOT guide. This guide is temporary, it will become a part of the user guide. The interesting point is that it's written in RST, and uses gerrit for reviews. So far we've had 2 core members of the heat team contributing content, and this content has been reviewed by other members of the team. The devs patches focused on content, not on the form of the content. I suggested to accept the patches rapidly - as long as they're technically correct - and to rework them later (what I've started to do a couple days ago). The fact that we're using gerrit and that the developers review each other work makes me more comfortable with the quality of the content. I'd really like to see this process extended to a larger part of the documentation, although this might not be needed everywhere. I had this workflow in mind: * a dev sends a review to a temporary repo * other devs can validate the information, and give their +1 when the patch is ready * a doc reviewer either requests more technical detail, or gives his +2/accept * the doc team reworks the patch and integrates it to the doc repository I really think that the process worked for the HOT guide, and I'm convinced that it could work for other parts of the doc (Cinder and Neutron drivers doc for instance). As a side note, we have a tool that converts RST to docbook. The hot guide is automatically built using this tool (http://docs.openstack.org/hot-guide/content/hot_guide_hot-guide.html). Gauvain ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Openstack-docs] Contributing to docs without Docbook -- YES you can!
Can someone create a Wiki for all the options available to contribute to openstack docs. I have a personel feeling that ArchWiki https://wiki.archlinux.org/index.php/Main_page is one of the best technical documentations available and they even have wiki for guidelines for writing. Can the the documentation process be open to all and then the admins can decide on what changes to accept and what to revert. s On Mon, Oct 6, 2014 at 10:35 AM, Gauvain Pocentek gauvain.pocen...@objectif-libre.com wrote: Le 2014-10-06 05:26, Tom Fifield a écrit : On 04/10/14 04:03, Nick Chase wrote: On Fri, Oct 3, 2014 at 3:07 PM, Stefano Maffulli stef...@openstack.org mailto:stef...@openstack.org wrote: 1. Pick an existing topic or create a new topic. For new topics, we're primarily interested in deployment scenarios. 2. Develop content (text and/or diagrams) in a format that supports at least basic markup (e.g., titles, paragraphs, lists, etc.). 3. Provide a link to the content (e.g., gist on github.com http://github.com, wiki page, blog post, etc.) under the associated topic. Points 1-3 seem to be oriented at removing Launchpad from the equation. Is that all there is? I guess it makes sense to remove obstacles, although editing the wiki (since it requires a launchpad account anyway) may not be the best way to track progress and see assignments. No, really, the main change is in step 5. Launchpad isn't the problem, as far as we can tell; Docbook is. Hi Nick, As best I can tell - 'step 5' has been in place for at least the last few summits at least, so this is not a change :) We have had a policy where anyone can dump text in bug reports and we'll wrangle it. This has been popular, see eg Marco Cossoni's contributions, but in my opinion not widely enough communicated - so thanks for your efforts. We actually have another way to work with developers, although it's been only available for the new HOT guide. This guide is temporary, it will become a part of the user guide. The interesting point is that it's written in RST, and uses gerrit for reviews. So far we've had 2 core members of the heat team contributing content, and this content has been reviewed by other members of the team. The devs patches focused on content, not on the form of the content. I suggested to accept the patches rapidly - as long as they're technically correct - and to rework them later (what I've started to do a couple days ago). The fact that we're using gerrit and that the developers review each other work makes me more comfortable with the quality of the content. I'd really like to see this process extended to a larger part of the documentation, although this might not be needed everywhere. I had this workflow in mind: * a dev sends a review to a temporary repo * other devs can validate the information, and give their +1 when the patch is ready * a doc reviewer either requests more technical detail, or gives his +2/accept * the doc team reworks the patch and integrates it to the doc repository I really think that the process worked for the HOT guide, and I'm convinced that it could work for other parts of the doc (Cinder and Neutron drivers doc for instance). As a side note, we have a tool that converts RST to docbook. The hot guide is automatically built using this tool (http://docs.openstack.org/ hot-guide/content/hot_guide_hot-guide.html). Gauvain ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Openstack-docs] Contributing to docs without Docbook -- YES you can!
Actually the documentation process is already open to all, and has been. You can find information on how to contribute here: https://wiki.openstack.org/wiki/Documentation/HowTo Thanks! Nick On Mon, Oct 6, 2014 at 1:23 AM, Akilesh K akilesh1...@gmail.com wrote: Can someone create a Wiki for all the options available to contribute to openstack docs. I have a personel feeling that ArchWiki https://wiki.archlinux.org/index.php/Main_page is one of the best technical documentations available and they even have wiki for guidelines for writing. Can the the documentation process be open to all and then the admins can decide on what changes to accept and what to revert. s ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Openstack-docs] Contributing to docs without Docbook -- YES you can!
hi Nick, On 09/29/2014 02:06 PM, Nicholas Chase wrote: Because we know that the networking documentation needs particular attention, we're starting there. We have a Networking Guide, from which we will ultimately pull information to improve the networking section of the admin guide. I love experiments and I appreciate your effort to improve the situation. It's not clear to me what the experiment wants to demonstrate and I'd appreciate more details. The preliminary Table of Contents is here: https://wiki.openstack.org/wiki/NetworkingGuide/TOC , and the instructions for contributing are as follows: This is cool and I see there is a blueprint also assigned https://blueprints.launchpad.net/openstack-manuals/+spec/create-networking-guide 1. Pick an existing topic or create a new topic. For new topics, we're primarily interested in deployment scenarios. 2. Develop content (text and/or diagrams) in a format that supports at least basic markup (e.g., titles, paragraphs, lists, etc.). 3. Provide a link to the content (e.g., gist on github.com, wiki page, blog post, etc.) under the associated topic. Points 1-3 seem to be oriented at removing Launchpad from the equation. Is that all there is? I guess it makes sense to remove obstacles, although editing the wiki (since it requires a launchpad account anyway) may not be the best way to track progress and see assignments. 4. Send e-mail to reviewers network...@openstacknow.com. Why not use the docs mailing list or other facilities on @openstack.org? Who is responding to that address? 5. A writer turns the content into an actual patch, with tracking bug, and docs reviewers (and the original author, we would hope) make sure it gets reviewed and merged. This is puzzling: initially I thought that you had some experimental magic software that would monitor edits to the wiki TOC page, go grab html content from gist, blog post, etc, transform that into docbook or something similar and magically create a task on LP for a doc writer to touch up and send for review. My understanding is that the Docs team has been using bug reports on Launchpad to receive contributions and a writer would pick them from the list, taking care of the transformation to docbook and gerrit workflow. Point 5. makes the experiment look like the process already in place, only using a wiki page first (instead of a blueprint first) and a private email address instead of a public bug tracker. Have I got it wrong? Can you explain a bit more why this experiment is not using the existing process? What is the experiment trying to demonstrate? /stef -- Ask and answer questions on https://ask.openstack.org ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Openstack-docs] Contributing to docs without Docbook -- YES you can!
On Fri, Oct 3, 2014 at 3:07 PM, Stefano Maffulli stef...@openstack.org wrote: hi Nick, On 09/29/2014 02:06 PM, Nicholas Chase wrote: Because we know that the networking documentation needs particular attention, we're starting there. We have a Networking Guide, from which we will ultimately pull information to improve the networking section of the admin guide. I love experiments and I appreciate your effort to improve the situation. It's not clear to me what the experiment wants to demonstrate and I'd appreciate more details. Absolutely. The preliminary Table of Contents is here: https://wiki.openstack.org/wiki/NetworkingGuide/TOC , and the instructions for contributing are as follows: This is cool and I see there is a blueprint also assigned https://blueprints.launchpad.net/openstack-manuals/+spec/create-networking-guide Correct. 1. Pick an existing topic or create a new topic. For new topics, we're primarily interested in deployment scenarios. 2. Develop content (text and/or diagrams) in a format that supports at least basic markup (e.g., titles, paragraphs, lists, etc.). 3. Provide a link to the content (e.g., gist on github.com, wiki page, blog post, etc.) under the associated topic. Points 1-3 seem to be oriented at removing Launchpad from the equation. Is that all there is? I guess it makes sense to remove obstacles, although editing the wiki (since it requires a launchpad account anyway) may not be the best way to track progress and see assignments. No, really, the main change is in step 5. Launchpad isn't the problem, as far as we can tell; Docbook is. 4. Send e-mail to reviewers network...@openstacknow.com. Why not use the docs mailing list or other facilities on @openstack.org? Who is responding to that address? If someone want to provide us a list on @openstack.org, that'd be awesome. I set up this address because I control the forwarding and could do it immediately without having to ask for anyone's approval. :) People on the alias are myself, Edgar Magana, Matt Kasawara, Phil Hopkins, Anne Gentle, and Elke Vorheis. 5. A writer turns the content into an actual patch, with tracking bug, and docs reviewers (and the original author, we would hope) make sure it gets reviewed and merged. This is puzzling: initially I thought that you had some experimental magic software that would monitor edits to the wiki TOC page, go grab html content from gist, blog post, etc, transform that into docbook or something similar and magically create a task on LP for a doc writer to touch up and send for review. Wouldn't THAT be fantastic. No, unfortunately not. This is a process experiment, rather than a technology experiment. My understanding is that the Docs team has been using bug reports on Launchpad to receive contributions and a writer would pick them from the list, taking care of the transformation to docbook and gerrit workflow. Bug reports are great, and we do want to continue getting those -- and the more information for the writer, the better! -- but that's a process where the developer says, hey, I think you should write something about X. This is the opposite. We're saying, Hey, we want to write about X, does anybody have any resources? Or if you think we should write about Y, do you have something already fleshed out (versus a paragraph you'd add in a bug report)? Point 5. makes the experiment look like the process already in place, only using a wiki page first (instead of a blueprint first) and a private email address instead of a public bug tracker. Well, you're half-right. It's like the process in already in place, only using a wiki page first and having a dedicated writer pick a developer's brain and actually produce the prose and put it into Docbook, rather than holding a gun to the developer's head and forcing him or her to write Docbook in order to contribute to the docs. Have I got it wrong? Can you explain a bit more why this experiment is not using the existing process? What is the experiment trying to demonstrate? The experiment is trying to determine whether we can increase the level of developer participation in the docs process by removing the hurtles of: 1) Deciphering where in the docs repo content goes 2) Learning XML in general, and Docbook in particular 3) Figuring out how to get docs to build 4) And so on, until the additions are actually merged Does that clear it up? Thanks... Nick /stef -- Ask and answer questions on https://ask.openstack.org ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
