-----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----- __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev