[openstack-dev] [Manila] Docs plan for Juno

Anne Gentle anne at openstack.org
Fri Sep 5 13:32:16 UTC 2014


Hi Ben,
Since manila just entered incubation, the openstack-manuals repo and common
documentation will not include it until it is integrated. During incubation
we ask you to start documentation in your own repo and identify what will
eventually move into common docs. See
https://wiki.openstack.org/wiki/Documentation/IncubateIntegrate.

You just got incubated, now what?

While you're incubating we like to see documentation in your repo in
doc/source, built with Sphinx. You can start to use the oslosphinx theme, a
common theme for OpenStack projects, at the point your project begins
incubation. You must indicate that you're incubating by setting the
oslosphinx configuration by ensuring your sphinx conf.py has incubating set
to True for the theme:

   'html_theme_options = {'incubating': True}'

You can publish to docs.openstack.org/developer while incubating. Prior to
incubation we suggest publishing to ReadTheDocs.org or your own domain and
avoid using the OpenStack logo or trademark unless you have permission as
outlined in the brand guidelines from http://www.openstack.org/brand/.

While you're incubating and gathering developer contributors, be sure to
also find writer resources. Your developers can probably manage the
contributor developer documentation but be thinking about how you'll write
your REST API reference documentation, your install documentation, your
configuration documentation, your operator and admin documentation, and
end-user documentation for CLI and dashboard interaction. You'll need to
prove you're able to support your users (ops, admins, and end-users) when
graduating to integrated, through docs and answers on ask.openstack.org.

While you're integrating, I'd suggest that your doc/source directory become
the landing place for your documentation. What you'll want to look forward
to is writing in such a way that your pages can be used for these
deliverables in the official OpenStack documentation, found at
https://wiki.openstack.org/wiki/Documentation/ContentSpecs.

Always be aware that the OpenStack Documentation Program prioritizes the
core projects above integrated, but we provide frameworks and reviews and
try to help with orientation as much as possible. We're just not in a
position to provide shared resources such as technical writers assigned to
each project, for example. Rather, we expect the projects to assign a doc
liaison who can interact with the documentation group through the
openstack-docs mailing list and #openstack-doc IRC channel. The docs team
holds weekly meetings and it's great to have doc liaisons attend the
meetings that are in their time zone. The meeting schedule and agenda are
found here: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting.




On Fri, Sep 5, 2014 at 7:27 AM, Swartzlander, Ben <
Ben.Swartzlander at netapp.com> wrote:

>  Now that the project is incubated, we should be moving our docs from the
> openstack wiki to the openstack-manuals project. Rushil Chugh has
> volunteered to lead this effort so please coordinate any updates to
> documentation with him (and me). Our goal is to have the updates to
> openstack-manuals upstream by Sept 22. It will go faster if we can split up
> the work and do it in parallel.
>
>
>
> -Ben
>
>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140905/67f4b343/attachment.html>


More information about the OpenStack-dev mailing list