Open Stack

Excerpts from Petr Kovar's message of 2018-05-28 16:03:41 +0200:
> On Thu, 24 May 2018 07:19:29 -0700
> "Jonathan D. Proulx" <jon at csail.mit.edu> wrote:
> 
> > My intention based on current understandign would be to create a git
> > repo called "osops-docs" as this fits current naming an thin initial
> > document we intend to put there and the others we may adopt from
> > docs-team.
> 
> So, just to clarify, the current plan is for your group to take ownership
> of the following docs?
> 
> https://github.com/openstack/openstack-manuals/tree/a1f1748478125ccd68d90a98ccc06c7ec359d3a0/doc/ops-guide
> https://github.com/openstack/openstack-manuals/tree/master/doc/arch-design
> https://github.com/openstack/openstack-manuals/tree/master/doc/ha-guide

Hmm, no, that's not what I thought we agreed to in the room.

During the Pike cycle the Docs team indicated that it could no longer
maintain the Operators Guide. That guide has *already* been handed off
to new owners. They are changing from hosting it in the wiki to using a
git repository. As part of that discussion, we talked about team
ownership, and they indicated that they still wanted to be independent
of the Documentation team.

Those other repositories did come up, but without clear contributors I
encouraged them to wait until they have the Operators Guide online
before they try to take on any more work. At that point we can have the
conversation about ownership.

> 
> Note that there is also
> https://github.com/openstack/openstack-manuals/tree/master/doc/ha-guide-draft
> which you probably want to merge with the ha-guide going forward (or
> retire one or the other).
> 
> As for naming the repo, this is really up to you, but it should be
> something clear and easily recognizable by your audience.
> 
> I can help with moving some of the content around, but as Doug pointed out,
> a few points about actual publishing need to be clarified first with the
> infra team.

The current plan is to create a SIG to own the repo so the owners
can publish the results to docs.openstack.org somewhere. The exact
URL is yet to be determined.

> 
>  > My understanding being they don't to have this type of
> > documentention due to much reduced team size and prefer it live with
> > subject matter experts. It that correct?  If that's not correct I'm
> > not personally opposed to trying this under docs.  We'll need to
> > maintain enough contributors and reviewers to make the work flow go in
> > either location and that's my understanding of the basic issue not
> > where it lives.
> 
> If you want more reviewers involved, I'd recommended inviting the reviewers
> from the docs group.

Yes, it would be good to have reviews from the existing documentation
team, especially any of them familiar with the content already and
have the time to help.

>  
> > This naming would also match other repos wich could be consolidated into an
> > "osops" repo to rule them all.  That may make sense as I think there's
> > significant overlap in set of people who might contribute, but that
> > can be a parallel conversation.
> > 
> > Doug looking at new project docs I think most of it is clear enough to
> > me.  Since it's not code I can skip all th PyPi stuff yes? The repo
> > creation seems pretty clear and I can steal the CI stuff from similar
> > projects.
> 
> Might be best to look into how https://github.com/openstack/security-doc is
> configured as that repo contains a number of separate documents, all managed
> by one group.

That may be a good example. I still think we want 1 guide per
repository, because it makes publishing much simpler.

> 
> > I'm a little unclear on the Storyboard bit I've not done
> > much contribution lately and haven't storyboarded.  Is that relevant
> > (or at least relevent at first) for this use case?  If it is I
> > probably have more questions.
> 
> I'd suggest either having your own storyboard or launchpad project so that
> users can file bugs somewhere, and give you feedback. storyboard might be a
> better option since all OpenStack projects all likely to migrate to it from
> launchpad at some point or another.

Yes, please use storyboard for anything new.

Doug

> 
> Cheers,
> pk
>