Open Stack

-----BEGIN PGP SIGNED MESSAGE-----
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

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

iQEcBAEBCAAGBQJW8x3JAAoJELppzVb4+KUy+UoIALNBcuOjdlwogj64zZ1eqIEO
fKYBOVtmoa2KhyNxDPT+QXFxrqkd0k/mOLR9fbJF6d7qWlb7od1Jix1r+wfYkKZh
Nq0zZ8nG+tPmHR9jtRoY6cZGxXHpJRLT8IBN86rMRdryi+xwtAyzbLz1frJ3QEbb
iGr1tllU+T6vN+QChM5R7fB7MA6U3GIARBxQ1Reye/U74UeLLzZTroN20Py0OMYi
5Vn440CLPXt0VbHt7JMe4Tv8vt33hNZGDe7V1vBBYaUWsFTXp1cjYChQUXCS/8xx
HPR0pWETOBo52NWqDkZRSI9LFuaVi+qh2oFzfhYfnOwKLh4tt4fFh2IWi3xIYFc=
=1HrY
-----END PGP SIGNATURE-----