[openstack-dev] [docs] Our Install Guides Only Cover Defcore - What about big tent?

Lana Brindley openstack at lanabrindley.com
Wed Mar 23 22:50:49 UTC 2016

Hash: SHA256

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.

>>> 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

Actually, I said that I acknowledge that isn't working, and we need to find a different solution.

> "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).

Yes, which is exactly what we'll be discussing at Summit.

> 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.

Thanks for mentioning this, we'll take it into account during our discussions.


- -- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
Version: GnuPG v2
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/


More information about the OpenStack-dev mailing list