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? > > Right. The solution to that isn't to say "we aren't going to document > > it at all" or "publish the documentation somewhere less ideal", > > though, which is what it sounds like we're doing now. It's to say > > Actually, I said that I acknowledge that isn't working, and we need to find a > different solution. OK, that wasn't clear to me from your message that continued to suggest publishing to a location under /developer. Doug __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
