Open Stack

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.

> 
> > 
> > The install docs team doesn't want to be swamped with everyone in big tent
> > giving them their install docs, to be verified, and eventually likely to be
> > maintained by the install docs team.
> 
> Which is exactly why we're very selective. Sadly, documenting every big tent project's install process is no small task.

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
"you are going to have to manage that document yourself, with the
docs team answering some questions to get you started using standard
templates for the document and build jobs".  We need a way for all
teams to publish things they write to locations outside of their
developer docs, without the documentation team feeling like they
are somehow responsible for the results (or, more importantly, for
readers of the documents to think that).

I like the prominent "file a bug here" link on the new docs theme,
so if we could reuse that but point the URL to the project's launchpad
site instead of the documentation team's site, that would be a
start. We may be able to do other things with the theme to further
indicate who created the content and how to get help or report
issues.

Doug