Re: [openstack-dev] [all][docs][tc] How to scale Documentation
On Mon, 06 Oct 2014 11:24:30 +0200 Julien Danjou jul...@danjou.info wrote: On Sun, Oct 05 2014, Joshua Harlow wrote: I agree. I think we should have documentation be part of our policy to accept patches, just as we do with e.g. unit testing. Forcing people to write documentation along the patch will help writing better code, having a better understanding of what the patch does for reviewers, etc… Agreed. And a lot of the confusion we get between what is documented to happen and what is implemented in the code is due to different people writing the documentation versus writing the code. And there has been insufficient information (other than the code) left for people to write accurate documentation. For API docs I wonder if we should bringing more of that into the project tree so we can enforce updating of documentation when the code gets updated. Chris ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all][docs][tc] How to scale Documentation
On Sun, Oct 05 2014, Joshua Harlow wrote: IMHO, it should be up to the project itself to provide the resources to work *under the guidance* of the Docs team to write developer, end user and operator documentation. The Docs team members should be able to play an advisory role for new projects, helping them understand the automated doc processes, the way that common doc infrastructure works, and techniques for writing useful documentation consistent with other projects. Best, -jay Amen to that, it is our responsibility as developers to do this, for the benefit of operators, developers, historians, ..., and users of openstack. And really it isn't that hard, you just have to devote some time to do it (take 1/2 of a day a week to devote to doing docs for your project). Eventually all those 1/2 of days add up to a decent set of usable docs for people using your project/library/other... If we had more people spending 1/2 or 1/4 a day a week on improving docstrings, improving api/sphinx docs, improving diagrams we would IMHO be in a much better position with respect to on-boarding new developers and making it so that existing developers can understand prior architectural decisions (which is important for a variety of reasons, including but not limited to 'knowing what the reason for this code was' which can be useful when/if refactoring, knowing what the reason for this code was when adding new tests...). IMHO we shouldn't be leaning on the docs team to do our docs, just like we shouldn't be leaning on the TC to say what is 'blessed' or what isn't; these roles should be advisory and I think they should be primarily spreading best practices, and leading by example (which I believe makes good leadership and a healthy community). I agree. I think we should have documentation be part of our policy to accept patches, just as we do with e.g. unit testing. Forcing people to write documentation along the patch will help writing better code, having a better understanding of what the patch does for reviewers, etc… And will obviously benefit to users and operators. -- Julien Danjou ;; Free Software hacker ;; http://julien.danjou.info signature.asc Description: PGP signature ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all][docs][tc] How to scale Documentation
On 10/06/2014 11:24 AM, Julien Danjou wrote: On Sun, Oct 05 2014, Joshua Harlow wrote: IMHO, it should be up to the project itself to provide the resources to work *under the guidance* of the Docs team to write developer, end user and operator documentation. The Docs team members should be able to play an advisory role for new projects, helping them understand the automated doc processes, the way that common doc infrastructure works, and techniques for writing useful documentation consistent with other projects. Best, -jay Amen to that, it is our responsibility as developers to do this, for the benefit of operators, developers, historians, ..., and users of openstack. And really it isn't that hard, you just have to devote some time to do it (take 1/2 of a day a week to devote to doing docs for your project). Eventually all those 1/2 of days add up to a decent set of usable docs for people using your project/library/other... If we had more people spending 1/2 or 1/4 a day a week on improving docstrings, improving api/sphinx docs, improving diagrams we would IMHO be in a much better position with respect to on-boarding new developers and making it so that existing developers can understand prior architectural decisions (which is important for a variety of reasons, including but not limited to 'knowing what the reason for this code was' which can be useful when/if refactoring, knowing what the reason for this code was when adding new tests...). IMHO we shouldn't be leaning on the docs team to do our docs, just like we shouldn't be leaning on the TC to say what is 'blessed' or what isn't; these roles should be advisory and I think they should be primarily spreading best practices, and leading by example (which I believe makes good leadership and a healthy community). I agree. I think we should have documentation be part of our policy to accept patches, just as we do with e.g. unit testing. Forcing people to write documentation along the patch will help writing better code, having a better understanding of what the patch does for reviewers, etc… And will obviously benefit to users and operators. This is a matter of making reviewers aware of this issue. As much as we want to make it official, there's probably not a good/easy way to enforce it besides asking reviewers to be nitpicky on these things. By requesting docs on reviews, we'll encourage people to write docs right away next time. Cheers, Flavio -- @flaper87 Flavio Percoco ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all][docs][tc] How to scale Documentation
-Original Message- From: Chris Friesen [mailto:chris.frie...@windriver.com] Sent: Saturday, October 04, 2014 1:27 PM To: openstack-dev@lists.openstack.org Subject: Re: [openstack-dev] [all][docs][tc] How to scale Documentation On 10/03/2014 07:50 PM, Anne Gentle wrote: Here's my current thinking and plan of attack on multiple fronts. Oh, that analogy is so militaristic, I'd revise more peacefully but ... time. :) 1. We need better page-based design and navigation for many of our docs. I'm working with the Foundation on a redesign. This may include simpler source files. 2. We still need book-like output. Examples of books include the Installation Guides, Operations Guide, the Security Guide, and probably the Architecture Design Guide. Every other bit of content can go into pages if we have decent design, information architecture, navigation, and versioning. Except maybe the API reference [0], that's a special beast. 3. We need better maintenance and care of app developer docs like the API Reference. This also includes simpler source files. Just curious, has anyone considered rejigging things so that each component has a single definition of its API that could then be used to mechanically generate both the API validation code as well as the API reference documentation? One idea related to the above, Nova will be able to provide API docs by auto-generating the docs from JSON-Home and JSON-Schema(API validation code). JSON-Home can provide API URLs, but it doesn't cover how to provide JSON-Schema now. If we make a consistent way for doing that in OpenStack components, we can get the docs on the same way/format. That was we told on the other thread[1]. Thanks Ken'ichi Ohmichi --- [1]: http://lists.openstack.org/pipermail/openstack-dev/2014-October/047635.html ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all][docs][tc] How to scale Documentation
Jay Pipes wrote: On 10/03/2014 09:18 PM, Zane Bitter wrote: The prospect of a much larger tent with many more projects in OpenStack-proper shines a spotlight on the scalability of the Docs team, and in particular how they decide which projects are important to work on directly. I don't believe that a ticket to live under the OpenStack tent should come with the expectation that the Docs team is required to write documentation for the project. IMHO, it should be up to the project itself to provide the resources to work *under the guidance* of the Docs team to write developer, end user and operator documentation. The Docs team members should be able to play an advisory role for new projects, helping them understand the automated doc processes, the way that common doc infrastructure works, and techniques for writing useful documentation consistent with other projects. I'd like to generalize that beyond Docs, because the same issue applies to all other horizontal teams. There are multiple ways an horizontal team can declare its commitment, and I agree we should never assume that a TC decision (new integrated project!) implies more work for the team (Docs now has to support this as well). That's the way it currently works, and yes, it doesn't scale. It didn't scale early with Docs, so they opted out of supporting all integrated projects early on. So in summary: - ticket to live under the OpenStack big tent should never come with expectation that any horizontal team will do the work for that project directly - horizontal teams may decide to directly do the work for any number of projects - corollary #1: horizontal teams may decide to commit to directly doing the work for a mostly-static ring0 (or not) - corollary #2: horizontal teams may decide to not directly do the work for any project - horizontal teams should build processes and tools to facilitate and guide the work of projects in the big tent in their area of expertise -- Thierry Carrez (ttx) ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all][docs][tc] How to scale Documentation
On 06/10/14 06:07, Thierry Carrez wrote: Jay Pipes wrote: On 10/03/2014 09:18 PM, Zane Bitter wrote: The prospect of a much larger tent with many more projects in OpenStack-proper shines a spotlight on the scalability of the Docs team, and in particular how they decide which projects are important to work on directly. I don't believe that a ticket to live under the OpenStack tent should come with the expectation that the Docs team is required to write documentation for the project. IMHO, it should be up to the project itself to provide the resources to work *under the guidance* of the Docs team to write developer, end user and operator documentation. The Docs team members should be able to play an advisory role for new projects, helping them understand the automated doc processes, the way that common doc infrastructure works, and techniques for writing useful documentation consistent with other projects. I'd like to generalize that beyond Docs, because the same issue applies to all other horizontal teams. There are multiple ways an horizontal team can declare its commitment, and I agree we should never assume that a TC decision (new integrated project!) implies more work for the team (Docs now has to support this as well). That's the way it currently works, and yes, it doesn't scale. It didn't scale early with Docs, so they opted out of supporting all integrated projects early on. So in summary: - ticket to live under the OpenStack big tent should never come with expectation that any horizontal team will do the work for that project directly - horizontal teams may decide to directly do the work for any number of projects - corollary #1: horizontal teams may decide to commit to directly doing the work for a mostly-static ring0 (or not) - corollary #2: horizontal teams may decide to not directly do the work for any project - horizontal teams should build processes and tools to facilitate and guide the work of projects in the big tent in their area of expertise +1 So it seems like there is general agreement that we don't need/want the TC to tell horizontal teams what to work on, and that isn't one of the reasons for ring0/ring compute/Layer 1 to be a thing? cheers, Zane. ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all][docs][tc] How to scale Documentation
I personally believe that delegating the task of documentation to individual projects would be a huge mistake for one big reason: documentation exists to understand how everything works within the context of the solution as a whole. Very hard to do that consistently across all projects with the docs team entrenched in developing individual products. Plus, enterprise adoption of the open cloud *requires* documentation that isn't an after thought. Writing code and trying to set aside some time to document is the sheer definition of turning documentation an afterthought - and no superior product has ever come from that sort of model. *Adam Lawson* AQORN, Inc. 427 North Tatnall Street Ste. 58461 Wilmington, Delaware 19801-2230 Toll-free: (844) 4-AQORN-NOW ext. 101 International: +1 302-387-4660 Direct: +1 916-246-2072 On Mon, Oct 6, 2014 at 8:40 AM, Zane Bitter zbit...@redhat.com wrote: On 06/10/14 06:07, Thierry Carrez wrote: Jay Pipes wrote: On 10/03/2014 09:18 PM, Zane Bitter wrote: The prospect of a much larger tent with many more projects in OpenStack-proper shines a spotlight on the scalability of the Docs team, and in particular how they decide which projects are important to work on directly. I don't believe that a ticket to live under the OpenStack tent should come with the expectation that the Docs team is required to write documentation for the project. IMHO, it should be up to the project itself to provide the resources to work *under the guidance* of the Docs team to write developer, end user and operator documentation. The Docs team members should be able to play an advisory role for new projects, helping them understand the automated doc processes, the way that common doc infrastructure works, and techniques for writing useful documentation consistent with other projects. I'd like to generalize that beyond Docs, because the same issue applies to all other horizontal teams. There are multiple ways an horizontal team can declare its commitment, and I agree we should never assume that a TC decision (new integrated project!) implies more work for the team (Docs now has to support this as well). That's the way it currently works, and yes, it doesn't scale. It didn't scale early with Docs, so they opted out of supporting all integrated projects early on. So in summary: - ticket to live under the OpenStack big tent should never come with expectation that any horizontal team will do the work for that project directly - horizontal teams may decide to directly do the work for any number of projects - corollary #1: horizontal teams may decide to commit to directly doing the work for a mostly-static ring0 (or not) - corollary #2: horizontal teams may decide to not directly do the work for any project - horizontal teams should build processes and tools to facilitate and guide the work of projects in the big tent in their area of expertise +1 So it seems like there is general agreement that we don't need/want the TC to tell horizontal teams what to work on, and that isn't one of the reasons for ring0/ring compute/Layer 1 to be a thing? cheers, Zane. ___ 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] [all][docs][tc] How to scale Documentation
On 10/06/2014 12:44 PM, Adam Lawson wrote: I personally believe that delegating the task of documentation to individual projects would be a huge mistake for one big reason: documentation exists to understand how everything works within the context of the solution as a whole. Very hard to do that consistently across all projects with the docs team entrenched in developing individual products. Plus, enterprise adoption of the open cloud /requires/ documentation that isn't an after thought. Writing code and trying to set aside some time to document is the sheer definition of turning documentation an afterthought - and no superior product has ever come from that sort of model. I hear your concerns about the possibility of getting documentation that is either inconsistent (with respect to the other OpenStack projects) or not written for the right audience if we only have developer contributors writing documentation. You have an excellent and prescient point. However, with my proposal, I was only saying that being under the OpenStack tent should not come with an automatic gift of resources from the excellent OpenStack Docs horizontal team. This process cannot scale. Instead, I believe it should be incumbent on the joining project to provide resources to work *with* the horizontal Docs team to provide foundational documentation for end users and operators. The Docs team can and should be advisors to the project contributors in how to write effective documentation targeted at non-developer contributors. In addition, please see my proposal that projects applying to be in the OpenStack tent would have a requirement to name both a Docs liaison as well as a Release Management liaison. [1] Best, -jay [1] http://www.joinfu.com/2014/09/answering-the-existential-question-in-openstack/ ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all][docs][tc] How to scale Documentation
I like your suggestion about the Docs team being advisors. I would submit however (my opinion here) that whether or not there are enough resources on the Doc'n team to handle Openstack's current list of integrated programs, offloading the work to individual projects exchanges one challenge (scalability) with another problem (quality). Using that approach, doc bugs will get triaged with the other project bugs and potentially distracts developers from doing what they do best - writing and fixing code. And what happens when you only have time to fix a feature or work on documentation? Focus on features and performance/stability are going to win. Every time. And they should because that what the program teams should be focused on. That means we start down the road heavy on code because developers can't do everything, making them light on documentation forcing a catch-up process to ensure which requires a special team to preserve momentum, bringing us back to where we are now. I've been there before. And I'm sure others have as well. I've always been a big proponent of exploiting strengths vs building on weaknesses and I'm going to step out on a limb here and speak to strengths which may get me into hot water with some so I want to apologize in advance. ; ) If a team of developers is tasked to produce all of the documentation for enterprise consumers, I hate to say it like this but you'll end up with highly-targeted documentation that makes sense to a developer and possibly low-level engineers. That level of detail is probably best served in README, wikis and mailing lists. It isn't effective as a user's manual. Even with coaching, we'd be coaching folks to do things they aren't good at. Same goes for a solution architect writing documentation the other way around - you end up with documentation that speaks so broad, it fails to make the impact that a targeted/focused approach is needed by the engineering consumers. While documentation produced by each individual project makes a special kind of impact, it must be one spoke - not the entire wheel. I love the idea of advisors and they should provide the first draft but I also believe a dedicated team is needed to ensure quality doesn't suffer. *Adam Lawson* AQORN, Inc. 427 North Tatnall Street Ste. 58461 Wilmington, Delaware 19801-2230 Toll-free: (844) 4-AQORN-NOW ext. 101 International: +1 302-387-4660 Direct: +1 916-246-2072 On Mon, Oct 6, 2014 at 9:59 AM, Jay Pipes jaypi...@gmail.com wrote: On 10/06/2014 12:44 PM, Adam Lawson wrote: I personally believe that delegating the task of documentation to individual projects would be a huge mistake for one big reason: documentation exists to understand how everything works within the context of the solution as a whole. Very hard to do that consistently across all projects with the docs team entrenched in developing individual products. Plus, enterprise adoption of the open cloud /requires/ documentation that isn't an after thought. Writing code and trying to set aside some time to document is the sheer definition of turning documentation an afterthought - and no superior product has ever come from that sort of model. I hear your concerns about the possibility of getting documentation that is either inconsistent (with respect to the other OpenStack projects) or not written for the right audience if we only have developer contributors writing documentation. You have an excellent and prescient point. However, with my proposal, I was only saying that being under the OpenStack tent should not come with an automatic gift of resources from the excellent OpenStack Docs horizontal team. This process cannot scale. Instead, I believe it should be incumbent on the joining project to provide resources to work *with* the horizontal Docs team to provide foundational documentation for end users and operators. The Docs team can and should be advisors to the project contributors in how to write effective documentation targeted at non-developer contributors. In addition, please see my proposal that projects applying to be in the OpenStack tent would have a requirement to name both a Docs liaison as well as a Release Management liaison. [1] Best, -jay [1] http://www.joinfu.com/2014/09/answering-the-existential- question-in-openstack/ ___ 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] [all][docs][tc] How to scale Documentation
On 10/06/2014 01:39 PM, Adam Lawson wrote: I like your suggestion about the Docs team being advisors. I would submit however (my opinion here) that whether or not there are enough resources on the Doc'n team to handle Openstack's current list of integrated programs, offloading the work to individual projects exchanges one challenge (scalability) with another problem (quality). Using that approach, doc bugs will get triaged with the other project bugs and potentially distracts developers from doing what they do best - writing and fixing code. And what happens when you only have time to fix a feature or work on documentation? Focus on features and performance/stability are going to win. Every time. And they should because that what the program teams should be focused on. That means we start down the road heavy on code because developers can't do everything, making them light on documentation forcing a catch-up process to ensure which requires a special team to preserve momentum, bringing us back to where we are now. I've been there before. And I'm sure others have as well. I've always been a big proponent of exploiting strengths vs building on weaknesses and I'm going to step out on a limb here and speak to strengths which may get me into hot water with some so I want to apologize in advance. ; ) If a team of developers is tasked to produce all of the documentation for enterprise consumers, I hate to say it like this but you'll end up with highly-targeted documentation that makes sense to a developer and possibly low-level engineers. That level of detail is probably best served in README, wikis and mailing lists. It isn't effective as a user's manual. Even with coaching, we'd be coaching folks to do things they aren't good at. Same goes for a solution architect writing documentation the other way around - you end up with documentation that speaks so broad, it fails to make the impact that a targeted/focused approach is needed by the engineering consumers. While documentation produced by each individual project makes a special kind of impact, it must be one spoke - not the entire wheel. I love the idea of advisors and they should provide the first draft but I also believe a dedicated team is needed to ensure quality doesn't suffer. I guess I wasn't clear in my suggestion. I am proposing that the joining project be responsible for bringing resources to the table -- and not developer resources, but tech writer resources. I think developers can and should work with the Docs team, but I also think that projects should hire or source tech writers themselves to handle the end user and operator documentation. Best, -jay ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all][docs][tc] How to scale Documentation
On 10/06/2014 11:39 AM, Adam Lawson wrote: I like your suggestion about the Docs team being advisors. I would submit however (my opinion here) that whether or not there are enough resources on the Doc'n team to handle Openstack's current list of integrated programs, offloading the work to individual projects exchanges one challenge (scalability) with another problem (quality). Using that approach, doc bugs will get triaged with the other project bugs and potentially distracts developers from doing what they do best - writing and fixing code. I think the point is that the individual projects can't have just developers...they also need to have people responsible for release management, integration testing, infrastructure, documentation, etc. Chris ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all][docs][tc] How to scale Documentation
On Mon, Oct 6, 2014 at 12:52 PM, Jay Pipes jaypi...@gmail.com wrote: On 10/06/2014 01:39 PM, Adam Lawson wrote: I like your suggestion about the Docs team being advisors. I would submit however (my opinion here) that whether or not there are enough resources on the Doc'n team to handle Openstack's current list of integrated programs, offloading the work to individual projects exchanges one challenge (scalability) with another problem (quality). Using that approach, doc bugs will get triaged with the other project bugs and potentially distracts developers from doing what they do best - writing and fixing code. And what happens when you only have time to fix a feature or work on documentation? Focus on features and performance/stability are going to win. Every time. And they should because that what the program teams should be focused on. That means we start down the road heavy on code because developers can't do everything, making them light on documentation forcing a catch-up process to ensure which requires a special team to preserve momentum, bringing us back to where we are now. I've been there before. And I'm sure others have as well. I've always been a big proponent of exploiting strengths vs building on weaknesses and I'm going to step out on a limb here and speak to strengths which may get me into hot water with some so I want to apologize in advance. ; ) If a team of developers is tasked to produce all of the documentation for enterprise consumers, I hate to say it like this but you'll end up with highly-targeted documentation that makes sense to a developer and possibly low-level engineers. That level of detail is probably best served in README, wikis and mailing lists. It isn't effective as a user's manual. Even with coaching, we'd be coaching folks to do things they aren't good at. Same goes for a solution architect writing documentation the other way around - you end up with documentation that speaks so broad, it fails to make the impact that a targeted/focused approach is needed by the engineering consumers. While documentation produced by each individual project makes a special kind of impact, it must be one spoke - not the entire wheel. I love the idea of advisors and they should provide the first draft but I also believe a dedicated team is needed to ensure quality doesn't suffer. I guess I wasn't clear in my suggestion. I am proposing that the joining project be responsible for bringing resources to the table -- and not developer resources, but tech writer resources. I think developers can and should work with the Docs team, but I also think that projects should hire or source tech writers themselves to handle the end user and operator documentation. This is happening with some projects and I always encourage companies hiring for OpenStack devs should also hire writers to keep up with those devs. Sometimes the tech writer is assigned only to the API docs not the operator docs. Or all sorts of other combinations. But yes, the idea is that the enterprise doc teams should also dedicate some of their work to upstream patching. And yes, I agree with the sentiment that it's pretty useless to document any project standalone for anyone except contributor devs. Users, operators, should write for users and operators upstream. Contrib devs write for devs in the commuity/upstream. Also hire tech writers who are good at advocating for particular groups and have them write for upstream as well. Lana Brindley and I are talking about that at the Summit Monday at 17:10 http://sched.co/1qeSZbp Nick Chase and I are working on a report about the balance between meeting the needs of community doc contributors and finding resources for enterprise-level deliverables. It's complicated, isn't it? It's a balancing act. Great discussion. Anne Best, -jay ___ 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] [all][docs][tc] How to scale Documentation
On 05/10/2014 06:00, Jay Pipes wrote: On 10/03/2014 09:18 PM, Zane Bitter wrote: The prospect of a much larger tent with many more projects in OpenStack-proper shines a spotlight on the scalability of the Docs team, and in particular how they decide which projects are important to work on directly. I don't believe that a ticket to live under the OpenStack tent should come with the expectation that the Docs team is required to write documentation for the project. IMHO, it should be up to the project itself to provide the resources to work *under the guidance* of the Docs team to write developer, end user and operator documentation. The Docs team members should be able to play an advisory role for new projects, helping them understand the automated doc processes, the way that common doc infrastructure works, and techniques for writing useful documentation consistent with other projects. Best, -jay ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev A huge +1 on this! You cannot expect the Docs team to understand and document a project - on the project team knows the ins and outs of the code, what it can do, and how to use it. This does not mean it should be a free for all. Work *with* the the Docs team to make the documentation standard and consistent across all of OpenStack. -- Maish Saidel-Keesing ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all][docs][tc] How to scale Documentation
One tool that ASF infra folks came up with was the Apache CMS, this helps the individual projects contribute to maintaining their documentation. They used Markdown format. Since we use DocBook, we could use a converter like pandoc (http://johnmacfarlane.net/pandoc/) later in the life cycle to use as input to our tools i guess. http://www.apache.org/dev/cmsref.html http://apache.org/dev/cms.html A quick tutorial is at - https://www.youtube.com/watch?v=xcDZN3Lu6HA thanks, dims On Sat, Oct 4, 2014 at 11:00 PM, Jay Pipes jaypi...@gmail.com wrote: On 10/03/2014 09:18 PM, Zane Bitter wrote: The prospect of a much larger tent with many more projects in OpenStack-proper shines a spotlight on the scalability of the Docs team, and in particular how they decide which projects are important to work on directly. I don't believe that a ticket to live under the OpenStack tent should come with the expectation that the Docs team is required to write documentation for the project. IMHO, it should be up to the project itself to provide the resources to work *under the guidance* of the Docs team to write developer, end user and operator documentation. The Docs team members should be able to play an advisory role for new projects, helping them understand the automated doc processes, the way that common doc infrastructure works, and techniques for writing useful documentation consistent with other projects. Best, -jay ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev -- Davanum Srinivas :: https://twitter.com/dims ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all][docs][tc] How to scale Documentation
On 10/04/2014 12:26 AM, Chris Friesen wrote: On 10/03/2014 07:50 PM, Anne Gentle wrote: Here's my current thinking and plan of attack on multiple fronts. Oh, that analogy is so militaristic, I'd revise more peacefully but ... time. :) 1. We need better page-based design and navigation for many of our docs. I'm working with the Foundation on a redesign. This may include simpler source files. 2. We still need book-like output. Examples of books include the Installation Guides, Operations Guide, the Security Guide, and probably the Architecture Design Guide. Every other bit of content can go into pages if we have decent design, information architecture, navigation, and versioning. Except maybe the API reference [0], that's a special beast. 3. We need better maintenance and care of app developer docs like the API Reference. This also includes simpler source files. Just curious, has anyone considered rejigging things so that each component has a single definition of its API that could then be used to mechanically generate both the API validation code as well as the API reference documentation? It seems silly to have to do the same work twice. That's what computers are for. :) Or is the up-front effort too high to make it worthwhile? This actually even came up on yesterday's bootstrapping hour. The point I think that Anne made quite well is that audience matters if you want to do it well (and not have it all come out like mud). It turns out what you provide for machines, is different than what you provide for devs, is different than what you provide for operators, is different than what you provide for users. It's a dev mindset trap that we can define it once in a language that makes sense to us, and just build a bunch of generators to turn it into understanding for everyone else. I know I fall victim to that a bunch. -Sean -- Sean Dague http://dague.net ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all][docs][tc] How to scale Documentation
On Fri, Oct 3, 2014 at 11:26 PM, Chris Friesen chris.frie...@windriver.com wrote: On 10/03/2014 07:50 PM, Anne Gentle wrote: Here's my current thinking and plan of attack on multiple fronts. Oh, that analogy is so militaristic, I'd revise more peacefully but ... time. :) 1. We need better page-based design and navigation for many of our docs. I'm working with the Foundation on a redesign. This may include simpler source files. 2. We still need book-like output. Examples of books include the Installation Guides, Operations Guide, the Security Guide, and probably the Architecture Design Guide. Every other bit of content can go into pages if we have decent design, information architecture, navigation, and versioning. Except maybe the API reference [0], that's a special beast. 3. We need better maintenance and care of app developer docs like the API Reference. This also includes simpler source files. Just curious, has anyone considered rejigging things so that each component has a single definition of its API that could then be used to mechanically generate both the API validation code as well as the API reference documentation? It seems silly to have to do the same work twice. That's what computers are for. :) Or is the up-front effort too high to make it worthwhile? To me, the upfront effort is better spent in better API docs. Starting with generated is fine, but generated API reference documentation doesn't tell users or quality engineers what's intended so that they can test APIs or write apps that won't break. Some reviewers were going to allow 200-299 error codes to get into the docs as a valid response since that's what the code does. [0] [1] That doesn't help users. We do talk about generating API docs, and testing APIs, and testing SDKs, quite a bit. Check out yesterday's Bootstrapping Hour [3] for more discussion about the balancing act and tradeoffs in generated docs. I know I toe the line a lot (not tow the line in this case, literally my toes are on a fine line). :) So great to know we're all thinking through this. It's a huge effort and we should optimize within an inch of that line. Thanks - Anne [0] https://review.openstack.org/#/c/120622/ [1] https://review.openstack.org/#/c/117193/ [2] https://www.youtube.com/watch?v=n2I3PFuoNj4 Chris ___ 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] [all][docs][tc] How to scale Documentation
On 10/03/2014 09:18 PM, Zane Bitter wrote: The prospect of a much larger tent with many more projects in OpenStack-proper shines a spotlight on the scalability of the Docs team, and in particular how they decide which projects are important to work on directly. I don't believe that a ticket to live under the OpenStack tent should come with the expectation that the Docs team is required to write documentation for the project. IMHO, it should be up to the project itself to provide the resources to work *under the guidance* of the Docs team to write developer, end user and operator documentation. The Docs team members should be able to play an advisory role for new projects, helping them understand the automated doc processes, the way that common doc infrastructure works, and techniques for writing useful documentation consistent with other projects. Best, -jay ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all][docs][tc] How to scale Documentation
On Sat, Oct 4, 2014 at 8:00 PM, Jay Pipes jaypi...@gmail.com wrote: On 10/03/2014 09:18 PM, Zane Bitter wrote: The prospect of a much larger tent with many more projects in OpenStack-proper shines a spotlight on the scalability of the Docs team, and in particular how they decide which projects are important to work on directly. I don't believe that a ticket to live under the OpenStack tent should come with the expectation that the Docs team is required to write documentation for the project. IMHO, it should be up to the project itself to provide the resources to work *under the guidance* of the Docs team to write developer, end user and operator documentation. The Docs team members should be able to play an advisory role for new projects, helping them understand the automated doc processes, the way that common doc infrastructure works, and techniques for writing useful documentation consistent with other projects. Best, -jay Amen to that, it is our responsibility as developers to do this, for the benefit of operators, developers, historians, ..., and users of openstack. And really it isn't that hard, you just have to devote some time to do it (take 1/2 of a day a week to devote to doing docs for your project). Eventually all those 1/2 of days add up to a decent set of usable docs for people using your project/library/other... If we had more people spending 1/2 or 1/4 a day a week on improving docstrings, improving api/sphinx docs, improving diagrams we would IMHO be in a much better position with respect to on-boarding new developers and making it so that existing developers can understand prior architectural decisions (which is important for a variety of reasons, including but not limited to 'knowing what the reason for this code was' which can be useful when/if refactoring, knowing what the reason for this code was when adding new tests...). IMHO we shouldn't be leaning on the docs team to do our docs, just like we shouldn't be leaning on the TC to say what is 'blessed' or what isn't; these roles should be advisory and I think they should be primarily spreading best practices, and leading by example (which I believe makes good leadership and a healthy community). My 2 cents, Josh ___ 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] [all][docs][tc] How to scale Documentation
Amidst all the discussion about layers and tents there has been this lurking issue about Docs and their need to prioritise work that we haven't really done a deep dive on yet. I'd like to start that discussion by summarising my understanding of the situation, and hopefully Anne and others can jump in and tell me what I've gotten horribly wrong. AIUI back in the day, all of the documentation for OpenStack was handled in a centralised way by the Docs team. We can all agree that doesn't scale, and that was recognised early on during the project's expansion. The current system is something of a hybrid model - for some subset of official projects considered important, the Docs team is directly responsible; for the others, the project team has to write the documentation. The docs team is available to provide support and tools for other official projects. It's not clear how important is currently defined... one suspects it's by date of accession ;) The prospect of a much larger tent with many more projects in OpenStack-proper shines a spotlight on the scalability of the Docs team, and in particular how they decide which projects are important to work on directly. There seems to be an implicit argument floating around that there are a bunch of projects that depend on each other and we need to create a governance structure around blessing this, rather than merely observing it as an emergent property of the gate, at least in part because that's the only way to tell the Docs team what is important. There are two problems with this line of thought IMHO. The obvious one is of course that the number of bi-directional dependencies of a project is not *in any way* related to how important it is to have documentation for it. It makes about as much sense as saying that we're only going to document projects whose names contain the letter 't'. The second is that it implies that the Docs team are the only people in OpenStack who need the TC to tell them what to work on. Developers generally work on what they or their employer feels is important. If you see something being neglected you either try to help out or pass the word up that more resources are needed in a particular area. Is there any reason to think it wouldn't work the same with technical writers? Is anyone seriously worried that Nova will go undocumented unless the TC creates a project structure that specifically calls it out as important? What I'm envisioning is that we would move to a completely distributed model, where the documentation for each project is owned by that project. People who care about the project being documented would either work on it themselves and/or recruit developers and/or technical writers to do so. The Docs program itself would concentrate on very high-level non-project-specific documentation and on standards and tools to help deliver a consistent presentation across projects. Of course we would expect there to be considerable overlap between the people contributing to the Docs program itself and those contributing to documentation of the various projects. Docs would also have a formal liaison program to ensure that information is disseminated rapidly and evenly. Is there any part of this that folks don't think would work? How many projects could it scale to? Is there a reason we need the TC to bless a subset of projects, or is it reasonable to expect that individual docs contributors can select what is most important to work on in much the same way that most contributors do? I know there are a lot of subtleties of which I have hitherto remained blissfully ignorant. Let's get those out in the open and get to the bottom of what impact, if any, the docs scaling issue needs to have on our governance structure. cheers, Zane. ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all][docs][tc] How to scale Documentation
On Fri, Oct 3, 2014 at 8:18 PM, Zane Bitter zbit...@redhat.com wrote: Amidst all the discussion about layers and tents there has been this lurking issue about Docs and their need to prioritise work that we haven't really done a deep dive on yet. I'd like to start that discussion by summarising my understanding of the situation, and hopefully Anne and others can jump in and tell me what I've gotten horribly wrong. AIUI back in the day, all of the documentation for OpenStack was handled in a centralised way by the Docs team. We can all agree that doesn't scale, and that was recognised early on during the project's expansion. The current system is something of a hybrid model - for some subset of official projects considered important, the Docs team is directly responsible; for the others, the project team has to write the documentation. The docs team is available to provide support and tools for other official projects. I think the Docs team isn't directly responsible for any project; we work with all projects. It's not clear how important is currently defined... one suspects it's by date of accession ;) There's more and more docs coverage in the common docs repos the longer a project has been around, but that's not always due to doc team only work. This wiki page attempts to describe current integrating/incubating processing for docs. https://wiki.openstack.org/wiki/Documentation/IncubateIntegrate Thing is, it's tough to say that any given project has completed docs. Nova still probably has the lead with the most doc bugs since Xen is barely documented and there are a lot of doc bugs for the Compute API versions. So it's possible to measure with our crude instruments and even with those measurements, inner chewy center projects could be called under-documented. The prospect of a much larger tent with many more projects in OpenStack-proper shines a spotlight on the scalability of the Docs team, and in particular how they decide which projects are important to work on directly. There seems to be an implicit argument floating around that there are a bunch of projects that depend on each other and we need to create a governance structure around blessing this, rather than merely observing it as an emergent property of the gate, at least in part because that's the only way to tell the Docs team what is important. There are two problems with this line of thought IMHO. The obvious one is of course that the number of bi-directional dependencies of a project is not *in any way* related to how important it is to have documentation for it. It makes about as much sense as saying that we're only going to document projects whose names contain the letter 't'. The second is that it implies that the Docs team are the only people in OpenStack who need the TC to tell them what to work on. Developers generally work on what they or their employer feels is important. If you see something being neglected you either try to help out or pass the word up that more resources are needed in a particular area. Is there any reason to think it wouldn't work the same with technical writers? Is anyone seriously worried that Nova will go undocumented unless the TC creates a project structure that specifically calls it out as important? What I'm envisioning is that we would move to a completely distributed model, where the documentation for each project is owned by that project. People who care about the project being documented would either work on it themselves and/or recruit developers and/or technical writers to do so. The Docs program itself would concentrate on very high-level non-project-specific documentation and on standards and tools to help deliver a consistent presentation across projects. Of course we would expect there to be considerable overlap between the people contributing to the Docs program itself and those contributing to documentation of the various projects. Docs would also have a formal liaison program to ensure that information is disseminated rapidly and evenly. I still maintain the thinking that common OpenStack docs are very valuable and the information architecture across projects could only go so far to truly serve users. Here's my current thinking and plan of attack on multiple fronts. Oh, that analogy is so militaristic, I'd revise more peacefully but ... time. :) 1. We need better page-based design and navigation for many of our docs. I'm working with the Foundation on a redesign. This may include simpler source files. 2. We still need book-like output. Examples of books include the Installation Guides, Operations Guide, the Security Guide, and probably the Architecture Design Guide. Every other bit of content can go into pages if we have decent design, information architecture, navigation, and versioning. Except maybe the API reference [0], that's a special beast. 3. We need better maintenance and care of app developer docs like the API
Re: [openstack-dev] [all][docs][tc] How to scale Documentation
On 10/03/2014 07:50 PM, Anne Gentle wrote: Here's my current thinking and plan of attack on multiple fronts. Oh, that analogy is so militaristic, I'd revise more peacefully but ... time. :) 1. We need better page-based design and navigation for many of our docs. I'm working with the Foundation on a redesign. This may include simpler source files. 2. We still need book-like output. Examples of books include the Installation Guides, Operations Guide, the Security Guide, and probably the Architecture Design Guide. Every other bit of content can go into pages if we have decent design, information architecture, navigation, and versioning. Except maybe the API reference [0], that's a special beast. 3. We need better maintenance and care of app developer docs like the API Reference. This also includes simpler source files. Just curious, has anyone considered rejigging things so that each component has a single definition of its API that could then be used to mechanically generate both the API validation code as well as the API reference documentation? It seems silly to have to do the same work twice. That's what computers are for. :) Or is the up-front effort too high to make it worthwhile? Chris ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
