Open Stack

----- Original Message -----
> From: "Anne Gentle" <anne at openstack.org>
> To: openstack-docs at lists.openstack.org
> Sent: Wednesday, June 25, 2014 10:56:20 AM
> Subject: [Openstack-docs] doc-specs repo?
> 
> Hi all,
> I wanted to hear more from the teams about a need for a doc-specs repo. The
> training team has started to bring specs into their repo. I'm happy to get
> this started for the Documentation program but wanted to get some input.
>
> I'd like to have an openstack/doc-spec repo set up with different
> directories for each area of the documentation. Some projects have
> designated by release as well, though since only our install guide and
> config guides are "released" I think we could just have:
> /api
> /training
> /user
> /appdev
> juno/ops (this is where install and config specs would live)
> /security

The layout looks OK to me for the most part- where would you put a proposal related to say the cloud-admin-guide in this structure (for example)? I'm assuming the intent here is it would go in user but to me it's not really user documentation (more operator targeted). I would also consider using ops as the top level category and the release (e.g. juno) as the second level one for consistency in the categorization at the top level, but that might just be my OCD kicking in.

On an unrelated note I'm also wondering if we should modify the structure of the openstack-manuals repository at some point to more clearly differentiate between the guides that are "released" and those that aren't. It's also still not really that obvious on the docs.openstack.org landing page either.

> Also, I don't think the developer template is useful to us. I'd like to
> have a template that is document centric. Here's a proposal:

[SNIP]

> 
> 
> What do you think about this approach?
> Thanks,
> Anne

I think this would be easier to discuss in the form of a patch proposal once the repository is created :). I think this is how creation of the original nova-specs template was handled as well.

Thanks,

Steve