On Fri, Mar 25, 2016 at 03:20:30PM -0400, 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.
Nope, it just works. Random examples: http://docs.openstack.org/developer/oslo.config/liberty/ http://docs.openstack.org/developer/oslo.config/mitaka/ http://docs.openstack.org/developer/oslo.config/3.4.0/ Just an undocumented feature of the docs job we found one day. :) // jim > > Doug > > > This gives a canonical place for deployers to look for the guide for > > their specific version, and solves the earlier piece about excluding the > > release series from the base URL (which I agree with). > > > > The downside being that intermediate releases (for ironic, today) cannot > > be updated if there's something missing or wrong; however that can > > easily be fixed by branching intermediate releases similar to what some > > other projects (telemetry?) do, if we decide that's valuable (though I > > don't like the idea of more backports to get a bug fix back to a given > > series). This is already a known caveat of using these URLs today, so I > > don't think it's worth blocking on. :) > > > > My only questions are how much work this will be (including all the > > redirects/rewrites that will need to happen), and where this happens (is > > it all within the infra projects, or is there also docs work that will > > need to happen?). > > > > // jim > > > > > > > > > > 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: 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 __________________________________________________________________________ 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