Re: [openstack-dev] [docs] Updating the docs team mission statement
I have updated the mission statement as per Thierry’s suggestion (thank you, I liked that a lot!) See the review here: https://review.openstack.org/#/c/499556/ It is currently in WIP. Petr and I agree that the best place to discuss this will be at the PTG. On 8/22/17, 5:34 PM, "Doug Hellmann"wrote: Excerpts from Jay S Bryant's message of 2017-08-22 11:06:37 -0500: > > On 8/22/2017 7:30 AM, Doug Hellmann wrote: > > Excerpts from Doug Hellmann's message of 2017-08-08 08:11:25 -0400: > >> Excerpts from Thierry Carrez's message of 2017-08-08 12:28:58 +0200: > >>> Petr Kovar wrote: > Hi all, > > With the core docs suite moving from openstack-manuals to individual > project repos as per > http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html, > it's also time to update the docs team mission statement from > https://governance.openstack.org/tc/reference/projects/documentation.html. > > What are everybody's thoughts on what should the new mission statement > say now that most OpenStack docs maintenance is in the hands of project > teams? > > One idea is for the docs team to act as a focused group of editors and > maintain a common set of guidelines, recommended practices (style > guidelines come to mind, for instance), and requirements (such as a common > docs and publishing structure shared across projects). > >>> I would say something like: > >>> > >>> The docs team provides guidance, assistance, tooling, and style guides > >>> enabling OpenStack project teams to produce consistent, accurate, and > >>> high-quality documentation. > >>> > >> Thanks for starting this thread, Petr. > >> > >> To make it easier to compare, here's the current mission statement: > >> > >>Provide documentation for core OpenStack projects to promote > >>OpenStack. Develop and maintain tools and processes to ensure > >>quality, accurate documentation. Treat documentation like OpenStack > >>code. > >> > >> Thierry's suggestion highlights some of the changes I see coming > >> for the docs team. I would like to hear from some of the other team > >> members about what they think about that. > >> > >> Doug > > This thread died out, but I think it's important that we make some > > progress on the discussion before the PTG because the outcome is > > going to influence the work we do there. > > > > One way we could approach it is to make a list of all of the things > > that the team is currently doing (or has been doing, up to Pike) > > and then review that list to consider which of those things, if the > > team was not already doing them, you would be willing to start doing > > today. That should establish a pattern for the types of tasks and > > initiatives the team thinks it can manage, and help us focus the > > mission statement. > > > > So, what does the docs team "do" or "make" today? > > > > Doug > > > > __ > > OpenStack Development Mailing List (not for usage questions) > > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > Doug, > > I think this is a good idea. Rather than writing a mission statement > and try to get what we do to fit it, we should look at what everyone is > doing and can do and then work to craft the statement from that. > > One important part in the process, however, would be to look at how that > compares to what was previously being done and make sure that there > aren't gaps. It is an opportunity to make sure we don't let anything > slip through the cracks. > > Jay > It's also an opportunity to identify things that should be dropped, or moved to another team. But yes, let's start by understanding what's actually happening today. Doug __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [docs] Updating the docs team mission statement
On 8/22/2017 11:33 AM, Doug Hellmann wrote: Excerpts from Jay S Bryant's message of 2017-08-22 11:06:37 -0500: On 8/22/2017 7:30 AM, Doug Hellmann wrote: Excerpts from Doug Hellmann's message of 2017-08-08 08:11:25 -0400: Excerpts from Thierry Carrez's message of 2017-08-08 12:28:58 +0200: Petr Kovar wrote: Hi all, With the core docs suite moving from openstack-manuals to individual project repos as per http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html, it's also time to update the docs team mission statement from https://governance.openstack.org/tc/reference/projects/documentation.html. What are everybody's thoughts on what should the new mission statement say now that most OpenStack docs maintenance is in the hands of project teams? One idea is for the docs team to act as a focused group of editors and maintain a common set of guidelines, recommended practices (style guidelines come to mind, for instance), and requirements (such as a common docs and publishing structure shared across projects). I would say something like: The docs team provides guidance, assistance, tooling, and style guides enabling OpenStack project teams to produce consistent, accurate, and high-quality documentation. Thanks for starting this thread, Petr. To make it easier to compare, here's the current mission statement: Provide documentation for core OpenStack projects to promote OpenStack. Develop and maintain tools and processes to ensure quality, accurate documentation. Treat documentation like OpenStack code. Thierry's suggestion highlights some of the changes I see coming for the docs team. I would like to hear from some of the other team members about what they think about that. Doug This thread died out, but I think it's important that we make some progress on the discussion before the PTG because the outcome is going to influence the work we do there. One way we could approach it is to make a list of all of the things that the team is currently doing (or has been doing, up to Pike) and then review that list to consider which of those things, if the team was not already doing them, you would be willing to start doing today. That should establish a pattern for the types of tasks and initiatives the team thinks it can manage, and help us focus the mission statement. So, what does the docs team "do" or "make" today? Doug __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev Doug, I think this is a good idea. Rather than writing a mission statement and try to get what we do to fit it, we should look at what everyone is doing and can do and then work to craft the statement from that. One important part in the process, however, would be to look at how that compares to what was previously being done and make sure that there aren't gaps. It is an opportunity to make sure we don't let anything slip through the cracks. Jay It's also an opportunity to identify things that should be dropped, or moved to another team. But yes, let's start by understanding what's actually happening today. Doug __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev Doug, Good point. There are also things that can be dropped and will have to be dropped given the changes in resources. It will need to be a thoughtful look at all the pieces. It will also be important as we look at what needs to be dropped from the core team that it is communicated to the project teams what they are expected to pick up. I have been figuring that out as I have been going and can try to help there but I am not sure that all the projects have been as active there. Jay __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [docs] Updating the docs team mission statement
Excerpts from Jay S Bryant's message of 2017-08-22 11:06:37 -0500: > > On 8/22/2017 7:30 AM, Doug Hellmann wrote: > > Excerpts from Doug Hellmann's message of 2017-08-08 08:11:25 -0400: > >> Excerpts from Thierry Carrez's message of 2017-08-08 12:28:58 +0200: > >>> Petr Kovar wrote: > Hi all, > > With the core docs suite moving from openstack-manuals to individual > project repos as per > http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html, > it's also time to update the docs team mission statement from > https://governance.openstack.org/tc/reference/projects/documentation.html. > > What are everybody's thoughts on what should the new mission statement > say now that most OpenStack docs maintenance is in the hands of project > teams? > > One idea is for the docs team to act as a focused group of editors and > maintain a common set of guidelines, recommended practices (style > guidelines come to mind, for instance), and requirements (such as a > common > docs and publishing structure shared across projects). > >>> I would say something like: > >>> > >>> The docs team provides guidance, assistance, tooling, and style guides > >>> enabling OpenStack project teams to produce consistent, accurate, and > >>> high-quality documentation. > >>> > >> Thanks for starting this thread, Petr. > >> > >> To make it easier to compare, here's the current mission statement: > >> > >>Provide documentation for core OpenStack projects to promote > >>OpenStack. Develop and maintain tools and processes to ensure > >>quality, accurate documentation. Treat documentation like OpenStack > >>code. > >> > >> Thierry's suggestion highlights some of the changes I see coming > >> for the docs team. I would like to hear from some of the other team > >> members about what they think about that. > >> > >> Doug > > This thread died out, but I think it's important that we make some > > progress on the discussion before the PTG because the outcome is > > going to influence the work we do there. > > > > One way we could approach it is to make a list of all of the things > > that the team is currently doing (or has been doing, up to Pike) > > and then review that list to consider which of those things, if the > > team was not already doing them, you would be willing to start doing > > today. That should establish a pattern for the types of tasks and > > initiatives the team thinks it can manage, and help us focus the > > mission statement. > > > > So, what does the docs team "do" or "make" today? > > > > Doug > > > > __ > > OpenStack Development Mailing List (not for usage questions) > > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > Doug, > > I think this is a good idea. Rather than writing a mission statement > and try to get what we do to fit it, we should look at what everyone is > doing and can do and then work to craft the statement from that. > > One important part in the process, however, would be to look at how that > compares to what was previously being done and make sure that there > aren't gaps. It is an opportunity to make sure we don't let anything > slip through the cracks. > > Jay > It's also an opportunity to identify things that should be dropped, or moved to another team. But yes, let's start by understanding what's actually happening today. Doug __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [docs] Updating the docs team mission statement
On 8/22/2017 7:30 AM, Doug Hellmann wrote: Excerpts from Doug Hellmann's message of 2017-08-08 08:11:25 -0400: Excerpts from Thierry Carrez's message of 2017-08-08 12:28:58 +0200: Petr Kovar wrote: Hi all, With the core docs suite moving from openstack-manuals to individual project repos as per http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html, it's also time to update the docs team mission statement from https://governance.openstack.org/tc/reference/projects/documentation.html. What are everybody's thoughts on what should the new mission statement say now that most OpenStack docs maintenance is in the hands of project teams? One idea is for the docs team to act as a focused group of editors and maintain a common set of guidelines, recommended practices (style guidelines come to mind, for instance), and requirements (such as a common docs and publishing structure shared across projects). I would say something like: The docs team provides guidance, assistance, tooling, and style guides enabling OpenStack project teams to produce consistent, accurate, and high-quality documentation. Thanks for starting this thread, Petr. To make it easier to compare, here's the current mission statement: Provide documentation for core OpenStack projects to promote OpenStack. Develop and maintain tools and processes to ensure quality, accurate documentation. Treat documentation like OpenStack code. Thierry's suggestion highlights some of the changes I see coming for the docs team. I would like to hear from some of the other team members about what they think about that. Doug This thread died out, but I think it's important that we make some progress on the discussion before the PTG because the outcome is going to influence the work we do there. One way we could approach it is to make a list of all of the things that the team is currently doing (or has been doing, up to Pike) and then review that list to consider which of those things, if the team was not already doing them, you would be willing to start doing today. That should establish a pattern for the types of tasks and initiatives the team thinks it can manage, and help us focus the mission statement. So, what does the docs team "do" or "make" today? Doug __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev Doug, I think this is a good idea. Rather than writing a mission statement and try to get what we do to fit it, we should look at what everyone is doing and can do and then work to craft the statement from that. One important part in the process, however, would be to look at how that compares to what was previously being done and make sure that there aren't gaps. It is an opportunity to make sure we don't let anything slip through the cracks. Jay __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [docs] Updating the docs team mission statement
Excerpts from Doug Hellmann's message of 2017-08-08 08:11:25 -0400: > Excerpts from Thierry Carrez's message of 2017-08-08 12:28:58 +0200: > > Petr Kovar wrote: > > > Hi all, > > > > > > With the core docs suite moving from openstack-manuals to individual > > > project repos as per > > > http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html, > > > it's also time to update the docs team mission statement from > > > https://governance.openstack.org/tc/reference/projects/documentation.html. > > > > > > What are everybody's thoughts on what should the new mission statement > > > say now that most OpenStack docs maintenance is in the hands of project > > > teams? > > > > > > One idea is for the docs team to act as a focused group of editors and > > > maintain a common set of guidelines, recommended practices (style > > > guidelines come to mind, for instance), and requirements (such as a common > > > docs and publishing structure shared across projects). > > > > I would say something like: > > > > The docs team provides guidance, assistance, tooling, and style guides > > enabling OpenStack project teams to produce consistent, accurate, and > > high-quality documentation. > > > > Thanks for starting this thread, Petr. > > To make it easier to compare, here's the current mission statement: > > Provide documentation for core OpenStack projects to promote > OpenStack. Develop and maintain tools and processes to ensure > quality, accurate documentation. Treat documentation like OpenStack > code. > > Thierry's suggestion highlights some of the changes I see coming > for the docs team. I would like to hear from some of the other team > members about what they think about that. > > Doug This thread died out, but I think it's important that we make some progress on the discussion before the PTG because the outcome is going to influence the work we do there. One way we could approach it is to make a list of all of the things that the team is currently doing (or has been doing, up to Pike) and then review that list to consider which of those things, if the team was not already doing them, you would be willing to start doing today. That should establish a pattern for the types of tasks and initiatives the team thinks it can manage, and help us focus the mission statement. So, what does the docs team "do" or "make" today? Doug __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [docs] Updating the docs team mission statement
On 08/08/2017 03:28 AM, Thierry Carrez wrote: Petr Kovar wrote: Hi all, With the core docs suite moving from openstack-manuals to individual project repos as per http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html, it's also time to update the docs team mission statement from https://governance.openstack.org/tc/reference/projects/documentation.html. What are everybody's thoughts on what should the new mission statement say now that most OpenStack docs maintenance is in the hands of project teams? One idea is for the docs team to act as a focused group of editors and maintain a common set of guidelines, recommended practices (style guidelines come to mind, for instance), and requirements (such as a common docs and publishing structure shared across projects). I think the team needs to be more than "editors". I agree with the rest of the statement and the direction Thierry provides below: I would say something like: The docs team provides guidance, assistance, tooling, and style guides enabling OpenStack project teams to produce consistent, accurate, and high-quality documentation. Note the doc team still has a few guides but I would not put emphasis on that, so the above is fine. Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [docs] Updating the docs team mission statement
Excerpts from Thierry Carrez's message of 2017-08-08 12:28:58 +0200: > Petr Kovar wrote: > > Hi all, > > > > With the core docs suite moving from openstack-manuals to individual > > project repos as per > > http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html, > > it's also time to update the docs team mission statement from > > https://governance.openstack.org/tc/reference/projects/documentation.html. > > > > What are everybody's thoughts on what should the new mission statement > > say now that most OpenStack docs maintenance is in the hands of project > > teams? > > > > One idea is for the docs team to act as a focused group of editors and > > maintain a common set of guidelines, recommended practices (style > > guidelines come to mind, for instance), and requirements (such as a common > > docs and publishing structure shared across projects). > > I would say something like: > > The docs team provides guidance, assistance, tooling, and style guides > enabling OpenStack project teams to produce consistent, accurate, and > high-quality documentation. > Thanks for starting this thread, Petr. To make it easier to compare, here's the current mission statement: Provide documentation for core OpenStack projects to promote OpenStack. Develop and maintain tools and processes to ensure quality, accurate documentation. Treat documentation like OpenStack code. Thierry's suggestion highlights some of the changes I see coming for the docs team. I would like to hear from some of the other team members about what they think about that. Doug __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [docs] Updating the docs team mission statement
Petr Kovar wrote: > Hi all, > > With the core docs suite moving from openstack-manuals to individual > project repos as per > http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html, > it's also time to update the docs team mission statement from > https://governance.openstack.org/tc/reference/projects/documentation.html. > > What are everybody's thoughts on what should the new mission statement > say now that most OpenStack docs maintenance is in the hands of project > teams? > > One idea is for the docs team to act as a focused group of editors and > maintain a common set of guidelines, recommended practices (style > guidelines come to mind, for instance), and requirements (such as a common > docs and publishing structure shared across projects). I would say something like: The docs team provides guidance, assistance, tooling, and style guides enabling OpenStack project teams to produce consistent, accurate, and high-quality documentation. -- Thierry Carrez (ttx) __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [docs] Updating the docs team mission statement
Hi all, With the core docs suite moving from openstack-manuals to individual project repos as per http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html, it's also time to update the docs team mission statement from https://governance.openstack.org/tc/reference/projects/documentation.html. What are everybody's thoughts on what should the new mission statement say now that most OpenStack docs maintenance is in the hands of project teams? One idea is for the docs team to act as a focused group of editors and maintain a common set of guidelines, recommended practices (style guidelines come to mind, for instance), and requirements (such as a common docs and publishing structure shared across projects). Other ideas, thoughts, or comments? Based on the feedback from the community, we plan to update https://governance.openstack.org/tc/reference/tags/docs_follows-policy.html too. Thanks, pk __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev