Open Stack

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/

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-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev