Open Stack

The only downside I see of these examples are there is no way in the
documentation to determine the release version or cycle.  (i.e. you have to
read the contents in conjunction with the URL).

Ronald Bradford

Web Site: http://ronaldbradford.com
LinkedIn:  http://www.linkedin.com/in/ronaldbradford
Twitter:    @RonaldBradford <http://twitter.com/ronaldbradford>
Skype:     RonaldBradford
GTalk:     Ronald.Bradford
IRC:         rbradfor


On Fri, Mar 25, 2016 at 4:20 PM, Jim Rollenhagen <jim at jimrollenhagen.com>
wrote:

> 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-request at 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-request at 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-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160328/b2ac5e41/attachment.html>