Open Stack

On Fri, Aug 30, 2013 at 8:31 AM, Julien Danjou <julien at danjou.info> wrote:

> On Fri, Aug 30 2013, Davanum Srinivas wrote:
>
> > How about mandating that when one adds a DocImpact in a review it should
> > have a url to an etherpad/wiki with sufficient information for the doc
> > team? yes, +1 to let docs team figure out where to fit it into existing
> > guides.
>
> That's a possibility.
>
> It still seems better to me to have the project's developers involved
> into the documentation than outsourcing it completely to another team.
> For example, there's no way to be sure the documentation team is going
> to understand what the developer meant on that wiki page, and that it'll
> then write correct instructions.
>

While we do have a nice spike in new contributors to the OpenStack docs
[1], we always have to refer to the original developer anyway, even with a
detailed blueprint / wiki page. So be involved and be ready for questions
from doc writers.


>
> Having the patches sent on the documented project directly makes sure
> developers are going to review it and that to the doc writer who's
> improving the documentation for example got things right.
>
>
For integrated projects, this is certainly the way to go, as the docs
program has had to draw the line at core. However, when people come to
docs.openstack.org, they want OpenStack docs. We need to get projects
fitting into the install guide, configuration guide, end user guide, admin
user guide, and so on. I'd like as much integrated information in those as
possible by October 17th. We do publish continuously so all the projects
need to get better at continuously updating docs.

I'd like to get docs closer to code all the time, but Sphinx hasn't met a
few crucial requirements: translation, content reuse, PDF, and comment
integration. I'd rather have repos and docs by audience than by project. To
repeat, people come to docs.openstack.org for OpenStack docs. Let's make
those better all the time.

Thanks,
Anne


1. https://github.com/openstack/openstack-manuals/graphs/contributors


>  --
> Julien Danjou
> -- Free Software hacker - independent consultant
> -- http://julien.danjou.info
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>


-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20130830/beda14cd/attachment.html>