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

Sean Dague sean at dague.net
Sat Oct 4 09:19:49 UTC 2014


On 10/04/2014 12:26 AM, Chris Friesen wrote:
> On 10/03/2014 07:50 PM, Anne Gentle wrote:
> 
>> Here's my current thinking and plan of attack on multiple fronts. Oh,
>> that analogy is so militaristic, I'd revise more peacefully but ...
>> time. :)
>>
>> 1. We need better page-based design and navigation for many of our docs.
>> I'm working with the Foundation on a redesign. This may include simpler
>> source files.
>> 2. We still need book-like output. Examples of books include the
>> Installation Guides, Operations Guide, the Security Guide, and probably
>> the Architecture Design Guide. Every other bit of content can go into
>> pages if we have decent design, information architecture, navigation,
>> and versioning. Except maybe the API reference [0], that's a special
>> beast.
>> 3. We need better maintenance and care of app developer docs like the
>> API Reference. This also includes simpler source files.
> 
> Just curious, has anyone considered rejigging things so that each
> component has a single definition of its API that could then be used to
> mechanically generate both the API validation code as well as the API
> reference documentation?
> 
> It seems silly to have to do the same work twice.  That's what computers
> are for. :)
> 
> Or is the up-front effort too high to make it worthwhile?

This actually even came up on yesterday's bootstrapping hour. The point
I think that Anne made quite well is that audience matters if you want
to do it well (and not have it all come out like mud). It turns out what
you provide for machines, is different than what you provide for devs,
is different than what you provide for operators, is different than what
you provide for users.

It's a dev mindset trap that we can define it once in a language that
makes sense to us, and just build a bunch of generators to turn it into
understanding for everyone else. I know I fall victim to that a bunch.

	-Sean

-- 
Sean Dague
http://dague.net



More information about the OpenStack-dev mailing list