Open Stack

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/

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
       HRB 21284 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126