Open Stack

Hi again all,

Thanks to Andreas we have the correct voting access list for the docs-specs
repo: https://review.openstack.org/#/c/103115/

I wanted to be sure we all understand when you do a spec. This is
especially important for docs-specs where you might be better off spending
time revising an actual patch rather than continuously revising a spec. A
spec can be used for:
- adding a large portion to an existing deliverable to ensure buy-in from
the core doc team
- adding an entirely new deliverable to the docs project
- any work that requires both content and tooling changes, such as the
addition of the API reference site, for sure that work needed a blueprint
- any large reorganization of a deliverable or set of deliverables
- automation work that will need to be designed prior to proposing a patch
- work that should definitely be discussed at a summit

Use bugs for:
- known content issues, even if you have to do multiple patches in order to
close the bug
- additions of content that is just plain missing
- known errors in the document

I want to ensure we balance out the need for up-front approval with "just
write it already" -- it's a balancing act and we all should start from a
point of agreement on these guidelines.

Feel free to ask for clarity -
Thanks,
Anne


On Fri, Jun 27, 2014 at 8:25 AM, Anne Gentle <anne at openstack.org> wrote:

>
>
>
> On Fri, Jun 27, 2014 at 7:59 AM, Andreas Jaeger <aj at suse.com> wrote:
>
>> On 06/27/2014 02:40 PM, Anne Gentle wrote:
>> >
>> >
>> >
>> > On Wed, Jun 25, 2014 at 3:22 PM, Sean Roberts <seanrob at yahoo-inc.com
>> > <mailto:seanrob at yahoo-inc.com>> wrote:
>> >
>> >     Having many sub-directories follows the docs layout because of the
>> >     different repos. If we go that way then we would need to treat each
>> >     project directory separate with their own release directories like
>> >     /doc-spec/training-guides/juno
>> >
>> >     The drawback will be that this makes finding approved specs
>> >     difficult. The other projects are using the single /specs directory
>> >     with a flat naming scheme like ml2-dell-afc-mech-driver.rst.
>> >
>> >     For specs that overlay projects like install-guides and
>> >     training-guides, it will be confusing which, what, where. Because of
>> >     this I vote for this structure
>> >
>> >     doc-spec -
>> >     specs -
>> >     juno - (all docs program juno cycle RST reside here)
>> >     tests -
>> >     doc -
>> >
>> >
>> >
>> > Yep, looks like that's the accepted structure.
>> >
>> > Here's the starting openstack-infra/config patch:
>> >
>> > https://review.openstack.org/103115
>> >
>> > and I'll populate the repo with this repo:
>> >
>> > https://github.com/annegentle/docs-specs
>>
>>
>> That repo contains many references to Glance - do you want to update it
>> first or do this later?
>>
>
> Updating now.
>
>
>>
>> Andreas
>> --
>>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
>>   SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>>    GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)
>>     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
>>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140630/dbe54699/attachment.html>