Re: [openstack-dev] The future of OpenStack documentation

2016-07-13 Thread Doug Hellmann
Excerpts from Matt Kassawara's message of 2016-07-13 09:52:45 -0600: > The configuration reference essentially uses a script to parse help strings > from code in project repositories. Occasionally, the documentation team > augments content beyond what the automation provides. However, these >

Re: [openstack-dev] The future of OpenStack documentation

2016-07-13 Thread Matt Kassawara
The configuration reference essentially uses a script to parse help strings from code in project repositories. Occasionally, the documentation team augments content beyond what the automation provides. However, these content augmentations, the script, and schedule for running the script belong to

Re: [openstack-dev] The future of OpenStack documentation

2016-07-13 Thread Markus Zoeller
On 11.07.2016 00:02, Steve Martinelli wrote: > I personally like this solution, it seems much more scalable. This follows > the same pattern of the API docs (moving the content to project repos), > which puts the onus back on the project team to maintain and create > documentation. I'm also hoping

Re: [openstack-dev] The future of OpenStack documentation

2016-07-12 Thread Lana Brindley
On 12/07/16 09:45, Matt Kassawara wrote: > Inline... > > On Sun, Jul 10, 2016 at 5:22 PM, Lana Brindley > wrote: > > On 09/07/16 07:02, Matt Kassawara wrote: > > Currently, OpenStack provides central documentation

Re: [openstack-dev] The future of OpenStack documentation

2016-07-11 Thread Matt Kassawara
Inline... On Sun, Jul 10, 2016 at 5:22 PM, Lana Brindley wrote: > On 09/07/16 07:02, Matt Kassawara wrote: > > Currently, OpenStack provides central documentation (primarily in the > openstack-manuals repository) for operators and users. The single location > and

Re: [openstack-dev] The future of OpenStack documentation

2016-07-11 Thread Lana Brindley
Matt, Can you please articulate the problem you're trying to solve? As Andreas says, we had specific problems that needed to be solved for the Install Guide and API docs, which is why they were done first. Lana On 12/07/16 08:26, Matt Kassawara wrote: > Andreas, > > I consider the API

Re: [openstack-dev] The future of OpenStack documentation

2016-07-11 Thread Matt Kassawara
Andreas, I consider the API documentation and installation guide rather complex for initial content to move to project repositories and evaluate the results. However, we're seeing rather strong adoption of moving API documentation which I think predicts adoption of moving operator/user

Re: [openstack-dev] The future of OpenStack documentation

2016-07-11 Thread Michael Johnson
I support putting infrastructure in place to allow the project documentation to be in the project's repository. We had problems in the Mitaka release with documentation getting deleted without the project team knowing it was happening until users were asking us where the documentation was

Re: [openstack-dev] The future of OpenStack documentation

2016-07-10 Thread Andreas Jaeger
With Install Guide and API references, we had specific problems to solve. Which ones do you see exactly with other guides? Also, before we discuss moving further documentation around, I'd like to see first how the API references and Install guides work out and what we need to improve there -

Re: [openstack-dev] The future of OpenStack documentation

2016-07-10 Thread Lana Brindley
On 09/07/16 07:02, Matt Kassawara wrote: > Currently, OpenStack provides central documentation (primarily in the > openstack-manuals repository) for operators and users. The single location > and consistent structure eases audiences of various technical expertise into > OpenStack, typically

Re: [openstack-dev] The future of OpenStack documentation

2016-07-10 Thread Steve Martinelli
I personally like this solution, it seems much more scalable. This follows the same pattern of the API docs (moving the content to project repos), which puts the onus back on the project team to maintain and create documentation. I'm also hoping this results in less duplication between the guides

[openstack-dev] The future of OpenStack documentation

2016-07-08 Thread Matt Kassawara
Currently, OpenStack provides central documentation (primarily in the openstack-manuals repository) for operators and users. The single location and consistent structure eases audiences of various technical expertise into OpenStack, typically operators and users rather than developers. Although