[openstack-dev] [all][docs][tc] How to scale Documentation

Davanum Srinivas davanum at gmail.com
Sun Oct 5 12:54:19 UTC 2014


One tool that ASF infra folks came up with was the Apache CMS, this
helps the individual projects contribute to maintaining their
documentation. They used Markdown format. Since we use DocBook, we
could use a converter like pandoc (http://johnmacfarlane.net/pandoc/)
later in the life cycle to use as input to our tools i guess.

http://www.apache.org/dev/cmsref.html
http://apache.org/dev/cms.html

A quick tutorial is at - https://www.youtube.com/watch?v=xcDZN3Lu6HA

thanks,
dims

On Sat, Oct 4, 2014 at 11:00 PM, Jay Pipes <jaypipes at gmail.com> wrote:
> On 10/03/2014 09:18 PM, Zane Bitter wrote:
>>
>> The prospect of a much larger tent with many more projects in
>> OpenStack-proper shines a spotlight on the scalability of the Docs team,
>> and in particular how they decide which projects are "important" to work
>> on directly.
>
>
> I don't believe that a ticket to live under the OpenStack tent should come
> with the expectation that the Docs team is required to write documentation
> for the project.
>
> IMHO, it should be up to the project itself to provide the resources to work
> *under the guidance* of the Docs team to write developer, end user and
> operator documentation. The Docs team members should be able to play an
> advisory role for new projects, helping them understand the automated doc
> processes, the way that common doc infrastructure works, and techniques for
> writing useful documentation consistent with other projects.
>
> Best,
> -jay
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



-- 
Davanum Srinivas :: https://twitter.com/dims



More information about the OpenStack-dev mailing list