Excerpts from Andreas Jaeger's message of 2016-03-25 20:30:01 +0100: > On 03/25/2016 08:20 PM, Doug Hellmann wrote: > > Excerpts from Jim Rollenhagen's message of 2016-03-25 10:45:30 -0700: > >> > On Fri, Mar 25, 2016 at 09:10:05AM -0400, Doug Hellmann wrote: > >>> > > Excerpts from Lana Brindley's message of 2016-03-24 08:50:49 +1000: > >>>> > > > On 24/03/16 08:01, Doug Hellmann wrote: > >>>>> > > > > Excerpts from Lana Brindley's message of 2016-03-24 07:14:35 > >>>>> > > > > +1000: > >>>>>> > > > >> Hi Mike, and sorry I missed you on IRC to discuss this there. > >>>>>> > > > >> That said, I think it's great that you took this to the > >>>>>> > > > >> mailing list, especially seeing the conversation that has > >>>>>> > > > >> ensued. > >>>>>> > > > >> > >>>>>> > > > >> More inline ... > >>>>>> > > > >> > >>>>>> > > > >> On 24/03/16 01:06, Mike Perez wrote: > >>>>>>> > > > >>> Hey all, > >>>>>>> > > > >>> > >>>>>>> > > > >>> I've been talking to a variety of projects about lack of > >>>>>>> > > > >>> install guides. This > >>>>>>> > > > >>> came from me not having a great experience with trying out > >>>>>>> > > > >>> projects in the big > >>>>>>> > > > >>> tent. > >>>>>>> > > > >>> > >>>>>>> > > > >>> Projects like Manila have proposed install docs [1], but > >>>>>>> > > > >>> they were rejected > >>>>>>> > > > >>> by the install docs team because it's not in defcore. One > >>>>>>> > > > >>> of Manila's goals of > >>>>>>> > > > >>> getting these docs accepted is to apply for the operators > >>>>>>> > > > >>> tag > >>>>>>> > > > >>> ops:docs:install-guide [2] so that it helps their maturity > >>>>>>> > > > >>> level in the project > >>>>>>> > > > >>> navigator [3]. > >>>>>>> > > > >>> > >>>>>>> > > > >>> Adrian Otto expressed to me having the same issue for > >>>>>>> > > > >>> Magnum. I think it's > >>>>>>> > > > >>> funny that a project that gets keynote time at the > >>>>>>> > > > >>> OpenStack conference can't > >>>>>>> > > > >>> be in the install docs personally. > >>>>>>> > > > >>> > >>>>>>> > > > >>> As seen from the Manila review [1], the install docs team > >>>>>>> > > > >>> is suggesting these > >>>>>>> > > > >>> to be put in their developer guide. > >>>>>> > > > >> > >>>>>> > > > >> As Steve pointed out, these now have solid plans to go in. > >>>>>> > > > >> That was because both projects opened a conversation with us > >>>>>> > > > >> and we worked with them over time to give them the docs they > >>>>>> > > > >> required. > >>>>>> > > > >> > >>>>>>> > > > >>> > >>>>>>> > > > >>> I don't think this is a great idea. Mainly because they are > >>>>>>> > > > >>> for developers, > >>>>>>> > > > >>> operators aren't going to be looking in there for install > >>>>>>> > > > >>> information. Also the > >>>>>>> > > > >>> Developer doc page [4] even states "This page contains > >>>>>>> > > > >>> documentation for Python > >>>>>>> > > > >>> developers, who work on OpenStack itself". > >>>>>> > > > >> > >>>>>> > > > >> I agree, but it's a great place to start. In fact, I've just > >>>>>> > > > >> merged a change to the Docs Contributor Guide (on the back of > >>>>>> > > > >> a previous mailing list conversation) that explicitly states > >>>>>> > > > >> this: > >>>>>> > > > >> > >>>>>> > > > >> http://docs.openstack.org/contributor-guide/quickstart/new-projects.html > >>>>> > > > > > >>>>> > > > > I think you're missing that most of us are disagreeing that it > >>>>> > > > > is > >>>>> > > > > a good place to start. It's fine to have the docs in a > >>>>> > > > > repository > >>>>> > > > > managed by the project team. It's not good at all to publish > >>>>> > > > > them > >>>>> > > > > under docs.o.o/developer because they are not for developers, > >>>>> > > > > and > >>>>> > > > > so it's confusing. This is why we ended up with a different > >>>>> > > > > place > >>>>> > > > > for release notes to be published, instead of just adding reno > >>>>> > > > > to > >>>>> > > > > the existing developer documentation build, for example. > >>>>> > > > > > >>>> > > > > >>>> > > > All docs need to be drafted somewhere. I don't care where that is, > >>>> > > > but make the suggestion of /developer because at least it's > >>>> > > > accessible there, and also because it's managed in the project's > >>>> > > > own repo. If you want to create a different place, or rename > >>>> > > > /developer to be more inclusive, I think that's a great idea. > >>> > > > >>> > > I think we'll want to add a new location, or publish to a similar > >>> > > location to the existing install guide. I found, for example > >>> > > http://docs.openstack.org/mitaka/install-guide-ubuntu/ > >>> > > > >>> > > If we take ironic as the example, and assume all OS-types would be > >>> > > covered in one manual, we could make that: > >>> > > > >>> > > (1) http://docs.openstack.org/mitaka/ironic/install-guide/ > >>> > > (2) http://docs.openstack.org/ironic/mitaka/install-guide/ > >>> > > (3) http://docs.openstack.org/install-guide/ironic/ > >>> > > (4) http://docs.openstack.org/ironic/install-guide/ > >>> > > > >>> > > I like options 3 and 4. To keep things simple for the project teams, > >>> > > I think we want to skip including the release series in the base > >>> > > URL. As the instructions change, projects may need to create > >>> > > separate sub-sections of their guide for each series, but they > >>> > > should be able to do that without having to set up separate publishing > >>> > > locations and jobs. > >>> > > > >>> > > Another benefit of options 3 and 4 is that as the ironic team > >>> > > produces other guides, those can go under a consistent URL that > >>> > > makes it relatively simple to set up a generic publishing job for > >>> > > all projects. Option 4 does have the benefit of making it easy to > >>> > > have a page at http://docs.openstack.org/ironic/ linking to all of > >>> > > the guides the ironic team has published. > >>> > > > >>> > > Thoughts? > >> > > >> > I also like 3 and 4. I like 3 because it's a similar structure to the > >> > developer docs, however I do like 4 giving us the option to publish > >> > other guides (and perhaps we could move the developer docs to > >> > /ironic/developer). > >> > > >> > I do think we should be able to publish per-release versions of the > >> > install guide (or any other guides) similar to how we publish developer > >> > docs per-release today. For example: > >> > http://docs.openstack.org/developer/ironic/liberty/ > >> > http://docs.openstack.org/developer/ironic/5.1.0/ > > Interesting, I wasn't aware of anyone doing that. Do you have custom doc > > build jobs in place? I could imagine this being useful for the Oslo > > libraries, too. > > This is how the infra publishing script is setup. > > So, just picking a random oslo lib, this exists: > > http://docs.openstack.org/developer/oslo.config/liberty/
Someone has been using the time machine. 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