Mailing List Archive

Thanks for kicking this off Chris.

Were you going to create that new repository? If not I can take on
the tasks of learning how and making it happen.

-Jon

On Wed, May 23, 2018 at 06:38:32PM -0700, Chris Morgan wrote:
: Hello Everyone,
: In the Ops Community documentation working session today in Vancouver,
: we made some really good progress (etherpad
: here: [1]https://etherpad.openstack.org/p/YVR-Ops-Community-Docs but
: not all of the good stuff is yet written down).
: In short, we're going to course correct on maintaining the Operators
: Guide, the HA Guide and Architecture Guide, not edit-in-place via the
: wiki and instead try still maintaining them as code, but with a
: different, new set of owners, possibly in a new Ops-focused repo. There
: was a strong consensus that a) code workflow >> wiki workflow and that
: b) openstack core docs tools are just fine.
: There is a lot still to be decided on how where and when, but we do
: have an offer of a rewrite of the HA Guide, as long as the changes will
: be allowed to actually land, so we expect to actually start showing
: some progress.
: At the end of the session, people wanted to know how to follow along as
: various people work out how to do this... and so for now that place is
: this very email thread. The idea is if the code for those documents
: goes to live in a different repo, or if new contributors turn up, or if
: a new version we will announce/discuss it here until such time as we
: have a better home for this initiative.
: Cheers
: Chris
: --
: Chris Morgan <[2]mihalis68@gmail.com>
:
:References
:
: 1. https://etherpad.openstack.org/p/YVR-Ops-Community-Docs
: 2. mailto:mihalis68@gmail.com

:_______________________________________________
:OpenStack-operators mailing list
:OpenStack-operators@lists.openstack.org
:http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators


_______________________________________________
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

I hadn’t got that far in my thoughts. If you’re able to give that a go, then that would be great!

Chris

Sent from my iPhone

> On May 23, 2018, at 6:46 PM, Jonathan D. Proulx <jon@csail.mit.edu> wrote:
>
>
> Thanks for kicking this off Chris.
>
> Were you going to create that new repository? If not I can take on
> the tasks of learning how and making it happen.
>
> -Jon
>
> On Wed, May 23, 2018 at 06:38:32PM -0700, Chris Morgan wrote:
> : Hello Everyone,
> : In the Ops Community documentation working session today in Vancouver,
> : we made some really good progress (etherpad
> : here: [1]https://etherpad.openstack.org/p/YVR-Ops-Community-Docs but
> : not all of the good stuff is yet written down).
> : In short, we're going to course correct on maintaining the Operators
> : Guide, the HA Guide and Architecture Guide, not edit-in-place via the
> : wiki and instead try still maintaining them as code, but with a
> : different, new set of owners, possibly in a new Ops-focused repo. There
> : was a strong consensus that a) code workflow >> wiki workflow and that
> : b) openstack core docs tools are just fine.
> : There is a lot still to be decided on how where and when, but we do
> : have an offer of a rewrite of the HA Guide, as long as the changes will
> : be allowed to actually land, so we expect to actually start showing
> : some progress.
> : At the end of the session, people wanted to know how to follow along as
> : various people work out how to do this... and so for now that place is
> : this very email thread. The idea is if the code for those documents
> : goes to live in a different repo, or if new contributors turn up, or if
> : a new version we will announce/discuss it here until such time as we
> : have a better home for this initiative.
> : Cheers
> : Chris
> : --
> : Chris Morgan <[2]mihalis68@gmail.com>
> :
> :References
> :
> : 1. https://etherpad.openstack.org/p/YVR-Ops-Community-Docs
> : 2. mailto:mihalis68@gmail.com
>
> :_______________________________________________
> :OpenStack-operators mailing list
> :OpenStack-operators@lists.openstack.org
> :http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>

_______________________________________________
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

You will want to follow the steps of the "project creators' guide"
[1]. Not all of them apply, because this is a docs repo and not a
code project repo. Let me know if you have questions about which
pieces do or do not apply as you go along, and we can work on
improving that document as well.

The openstack/tripleo-docs repo looks like it has a setup similar
to the one you'll be creating, so when you get to the steps about
setting up jobs you can probably copy what they have.

After the session today it occurred to me that there is one
governance-related thing that we would need to do in order to publish
this content to docs.openstack.org. Right now we have a policy that
only official teams can do that. I think if the guide is owned by
a SIG or other group chartered either by the TC or UC we can make
that work. We can do quite a lot of the setup work while we figure
that out, though, so don't lose momentum in the mean time.

Doug

[1] https://docs.openstack.org/infra/manual/creators.html

Excerpts from Chris Morgan's message of 2018-05-23 20:09:05 -0700:
> I hadn’t got that far in my thoughts. If you’re able to give that a go, then that would be great!
>
> Chris
>
> Sent from my iPhone
>
> > On May 23, 2018, at 6:46 PM, Jonathan D. Proulx <jon@csail.mit.edu> wrote:
> >
> >
> > Thanks for kicking this off Chris.
> >
> > Were you going to create that new repository? If not I can take on
> > the tasks of learning how and making it happen.
> >
> > -Jon
> >
> > On Wed, May 23, 2018 at 06:38:32PM -0700, Chris Morgan wrote:
> > : Hello Everyone,
> > : In the Ops Community documentation working session today in Vancouver,
> > : we made some really good progress (etherpad
> > : here: [1]https://etherpad.openstack.org/p/YVR-Ops-Community-Docs but
> > : not all of the good stuff is yet written down).
> > : In short, we're going to course correct on maintaining the Operators
> > : Guide, the HA Guide and Architecture Guide, not edit-in-place via the
> > : wiki and instead try still maintaining them as code, but with a
> > : different, new set of owners, possibly in a new Ops-focused repo. There
> > : was a strong consensus that a) code workflow >> wiki workflow and that
> > : b) openstack core docs tools are just fine.
> > : There is a lot still to be decided on how where and when, but we do
> > : have an offer of a rewrite of the HA Guide, as long as the changes will
> > : be allowed to actually land, so we expect to actually start showing
> > : some progress.
> > : At the end of the session, people wanted to know how to follow along as
> > : various people work out how to do this... and so for now that place is
> > : this very email thread. The idea is if the code for those documents
> > : goes to live in a different repo, or if new contributors turn up, or if
> > : a new version we will announce/discuss it here until such time as we
> > : have a better home for this initiative.
> > : Cheers
> > : Chris
> > : --
> > : Chris Morgan <[2]mihalis68@gmail.com>
> > :
> > :References
> > :
> > : 1. https://etherpad.openstack.org/p/YVR-Ops-Community-Docs
> > : 2. mailto:mihalis68@gmail.com
> >
> > :_______________________________________________
> > :OpenStack-operators mailing list
> > :OpenStack-operators@lists.openstack.org
> > :http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
> >
>

_______________________________________________
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

Hi Chris,

thanks for summarize our session today in Vancouver. As I18n PTL and one
of the Docs Core I put Petr in Cc. He is currently Docs PTL, but
unfortunatelly not on-site.
I couldn't also not get the full history of the story and that's also
not the idea to starting finger pointing. As usualy we moving forward
and there are some interesting things to know what happened.
First of all: There are no "Docs-Team" anymore. If you look at [1] there
are mostly part-time contributors like me or people are more involved in
other projects and therefore busy. Because of that, the responsibility
of documentation content are moved completely to the project teams. Each
repo has a user guide, admin guide, deployment guide, and so on. The
small Documentation Team provides only tooling and give advices how to
write and publish a document. So it's up to you to re-use the old repo
on [2] or setup a new one. I would recommend to use the best of both
worlds. There are a very good toolset in place for testing and
publishing documents. There are also various text editors for rst
extensions available, like in vim, notepad++ or also online services. I
understand the concerns and when people are sad because their patches
are ignored for months. But it's alltime a question of responsibilty and
how can spend people time.
I would be available for help. As I18n PTL I could imagine that a
OpenStack Operations Guide is available in different languages and
portable in different formats like in Sphinx. For us as translation team
it's a good possibility to get feedback about the quality and to
understand the requirements, also for other documents.
So let's move on.

kind regards

Frank

[1] https://review.openstack.org/#/admin/groups/30,members
[2] https://github.com/openstack/operations-guide

Am 2018-05-24 03:38, schrieb Chris Morgan:
> Hello Everyone,
>
> In the Ops Community documentation working session today in Vancouver,
> we made some really good progress (etherpad here:
> https://etherpad.openstack.org/p/YVR-Ops-Community-Docs but not all of
> the good stuff is yet written down).
>
> In short, we're going to course correct on maintaining the Operators
> Guide, the HA Guide and Architecture Guide, not edit-in-place via the
> wiki and instead try still maintaining them as code, but with a
> different, new set of owners, possibly in a new Ops-focused repo.
> There was a strong consensus that a) code workflow >> wiki workflow
> and that b) openstack core docs tools are just fine.
>
> There is a lot still to be decided on how where and when, but we do
> have an offer of a rewrite of the HA Guide, as long as the changes
> will be allowed to actually land, so we expect to actually start
> showing some progress.
>
> At the end of the session, people wanted to know how to follow along
> as various people work out how to do this... and so for now that place
> is this very email thread. The idea is if the code for those documents
> goes to live in a different repo, or if new contributors turn up, or
> if a new version we will announce/discuss it here until such time as
> we have a better home for this initiative.
>
> Cheers
>
> Chris
>
> --
> Chris Morgan <mihalis68@gmail.com>
> _______________________________________________
> OpenStack-operators mailing list
> OpenStack-operators@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators


_______________________________________________
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

Great to see this moving. I have some questions/concerns based on your
statement Doug about docs.openstack.org publishing and do not want to
detour the conversation but ask for feedback. Currently there are a number
of repositories under osops-

https://github.com/openstack-infra/project-config/blob/master/gerrit/projects.yaml#L5673-L5703

Generally active:
osops-tools-contrib
osops-tools-generic
osops-tools-monitoring


Probably dead:
osops-tools-logging
osops-coda
osops-example-configs

Because you are more familiar with how things work, is there a way to
consolidate these vs coming up with another repo like osops-docs or
whatever in this case? And second, is there already governance clearance to
publish based on the following - https://launchpad.net/osops - which is
where these repos originated.


On Wed, May 23, 2018 at 9:56 PM, Frank Kloeker <eumel@arcor.de> wrote:

> Hi Chris,
>
> thanks for summarize our session today in Vancouver. As I18n PTL and one
> of the Docs Core I put Petr in Cc. He is currently Docs PTL, but
> unfortunatelly not on-site.
> I couldn't also not get the full history of the story and that's also not
> the idea to starting finger pointing. As usualy we moving forward and there
> are some interesting things to know what happened.
> First of all: There are no "Docs-Team" anymore. If you look at [1] there
> are mostly part-time contributors like me or people are more involved in
> other projects and therefore busy. Because of that, the responsibility of
> documentation content are moved completely to the project teams. Each repo
> has a user guide, admin guide, deployment guide, and so on. The small
> Documentation Team provides only tooling and give advices how to write and
> publish a document. So it's up to you to re-use the old repo on [2] or
> setup a new one. I would recommend to use the best of both worlds. There
> are a very good toolset in place for testing and publishing documents.
> There are also various text editors for rst extensions available, like in
> vim, notepad++ or also online services. I understand the concerns and when
> people are sad because their patches are ignored for months. But it's
> alltime a question of responsibilty and how can spend people time.
> I would be available for help. As I18n PTL I could imagine that a
> OpenStack Operations Guide is available in different languages and portable
> in different formats like in Sphinx. For us as translation team it's a good
> possibility to get feedback about the quality and to understand the
> requirements, also for other documents.
> So let's move on.
>
> kind regards
>
> Frank
>
> [1] https://review.openstack.org/#/admin/groups/30,members
> [2] https://github.com/openstack/operations-guide
>
>
> Am 2018-05-24 03:38, schrieb Chris Morgan:
>
>> Hello Everyone,
>>
>> In the Ops Community documentation working session today in Vancouver,
>> we made some really good progress (etherpad here:
>> https://etherpad.openstack.org/p/YVR-Ops-Community-Docs but not all of
>> the good stuff is yet written down).
>>
>> In short, we're going to course correct on maintaining the Operators
>> Guide, the HA Guide and Architecture Guide, not edit-in-place via the
>> wiki and instead try still maintaining them as code, but with a
>> different, new set of owners, possibly in a new Ops-focused repo.
>> There was a strong consensus that a) code workflow >> wiki workflow
>> and that b) openstack core docs tools are just fine.
>>
>> There is a lot still to be decided on how where and when, but we do
>> have an offer of a rewrite of the HA Guide, as long as the changes
>> will be allowed to actually land, so we expect to actually start
>> showing some progress.
>>
>> At the end of the session, people wanted to know how to follow along
>> as various people work out how to do this... and so for now that place
>> is this very email thread. The idea is if the code for those documents
>> goes to live in a different repo, or if new contributors turn up, or
>> if a new version we will announce/discuss it here until such time as
>> we have a better home for this initiative.
>>
>> Cheers
>>
>> Chris
>>
>> --
>> Chris Morgan <mihalis68@gmail.com>
>> _______________________________________________
>> OpenStack-operators mailing list
>> OpenStack-operators@lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>>
>
>
> _______________________________________________
> OpenStack-operators mailing list
> OpenStack-operators@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>



--
Kind regards,

Melvin Hillsman
mrhillsman@gmail.com
mobile: (832) 264-2646

Also, apologies, if consolidation or reorganizing all these is reasonable,
what do you think that would look like; i.e.

osops
> tools
>> contrib
>> generic
>> monitoring
>> logging
> docs
> example-configs


On Wed, May 23, 2018 at 10:26 PM, Melvin Hillsman <mrhillsman@gmail.com>
wrote:

> Great to see this moving. I have some questions/concerns based on your
> statement Doug about docs.openstack.org publishing and do not want to
> detour the conversation but ask for feedback. Currently there are a number
> of repositories under osops-
>
> https://github.com/openstack-infra/project-config/blob/
> master/gerrit/projects.yaml#L5673-L5703
>
> Generally active:
> osops-tools-contrib
> osops-tools-generic
> osops-tools-monitoring
>
>
> Probably dead:
> osops-tools-logging
> osops-coda
> osops-example-configs
>
> Because you are more familiar with how things work, is there a way to
> consolidate these vs coming up with another repo like osops-docs or
> whatever in this case? And second, is there already governance clearance to
> publish based on the following - https://launchpad.net/osops - which is
> where these repos originated.
>
>
> On Wed, May 23, 2018 at 9:56 PM, Frank Kloeker <eumel@arcor.de> wrote:
>
>> Hi Chris,
>>
>> thanks for summarize our session today in Vancouver. As I18n PTL and one
>> of the Docs Core I put Petr in Cc. He is currently Docs PTL, but
>> unfortunatelly not on-site.
>> I couldn't also not get the full history of the story and that's also not
>> the idea to starting finger pointing. As usualy we moving forward and there
>> are some interesting things to know what happened.
>> First of all: There are no "Docs-Team" anymore. If you look at [1] there
>> are mostly part-time contributors like me or people are more involved in
>> other projects and therefore busy. Because of that, the responsibility of
>> documentation content are moved completely to the project teams. Each repo
>> has a user guide, admin guide, deployment guide, and so on. The small
>> Documentation Team provides only tooling and give advices how to write and
>> publish a document. So it's up to you to re-use the old repo on [2] or
>> setup a new one. I would recommend to use the best of both worlds. There
>> are a very good toolset in place for testing and publishing documents.
>> There are also various text editors for rst extensions available, like in
>> vim, notepad++ or also online services. I understand the concerns and when
>> people are sad because their patches are ignored for months. But it's
>> alltime a question of responsibilty and how can spend people time.
>> I would be available for help. As I18n PTL I could imagine that a
>> OpenStack Operations Guide is available in different languages and portable
>> in different formats like in Sphinx. For us as translation team it's a good
>> possibility to get feedback about the quality and to understand the
>> requirements, also for other documents.
>> So let's move on.
>>
>> kind regards
>>
>> Frank
>>
>> [1] https://review.openstack.org/#/admin/groups/30,members
>> [2] https://github.com/openstack/operations-guide
>>
>>
>> Am 2018-05-24 03:38, schrieb Chris Morgan:
>>
>>> Hello Everyone,
>>>
>>> In the Ops Community documentation working session today in Vancouver,
>>> we made some really good progress (etherpad here:
>>> https://etherpad.openstack.org/p/YVR-Ops-Community-Docs but not all of
>>> the good stuff is yet written down).
>>>
>>> In short, we're going to course correct on maintaining the Operators
>>> Guide, the HA Guide and Architecture Guide, not edit-in-place via the
>>> wiki and instead try still maintaining them as code, but with a
>>> different, new set of owners, possibly in a new Ops-focused repo.
>>> There was a strong consensus that a) code workflow >> wiki workflow
>>> and that b) openstack core docs tools are just fine.
>>>
>>> There is a lot still to be decided on how where and when, but we do
>>> have an offer of a rewrite of the HA Guide, as long as the changes
>>> will be allowed to actually land, so we expect to actually start
>>> showing some progress.
>>>
>>> At the end of the session, people wanted to know how to follow along
>>> as various people work out how to do this... and so for now that place
>>> is this very email thread. The idea is if the code for those documents
>>> goes to live in a different repo, or if new contributors turn up, or
>>> if a new version we will announce/discuss it here until such time as
>>> we have a better home for this initiative.
>>>
>>> Cheers
>>>
>>> Chris
>>>
>>> --
>>> Chris Morgan <mihalis68@gmail.com>
>>> _______________________________________________
>>> OpenStack-operators mailing list
>>> OpenStack-operators@lists.openstack.org
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>>>
>>
>>
>> _______________________________________________
>> OpenStack-operators mailing list
>> OpenStack-operators@lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>>
>
>
>
> --
> Kind regards,
>
> Melvin Hillsman
> mrhillsman@gmail.com
> mobile: (832) 264-2646
>



--
Kind regards,

Melvin Hillsman
mrhillsman@gmail.com
mobile: (832) 264-2646

Excerpts from Melvin Hillsman's message of 2018-05-23 22:26:02 -0700:
> Great to see this moving. I have some questions/concerns based on your
> statement Doug about docs.openstack.org publishing and do not want to
> detour the conversation but ask for feedback. Currently there are a number

I'm just unclear on that, but don't consider it a blocker. We will sort
out whatever governance or policy change is needed to let this move
forward.

> of repositories under osops-
>
> https://github.com/openstack-infra/project-config/blob/master/gerrit/projects.yaml#L5673-L5703
>
> Generally active:
> osops-tools-contrib
> osops-tools-generic
> osops-tools-monitoring
>
>
> Probably dead:
> osops-tools-logging
> osops-coda
> osops-example-configs
>
> Because you are more familiar with how things work, is there a way to
> consolidate these vs coming up with another repo like osops-docs or
> whatever in this case? And second, is there already governance clearance to
> publish based on the following - https://launchpad.net/osops - which is
> where these repos originated.

I don't really know what any of those things are, or whether it
makes sense to put this new content there. I assumed we would make
a repo with a name like "operations-guide", but that's up to Chris
and John. If they think reusing an existing repository makes sense,
that would be OK with me, but it's cheap and easy to set up a new
one, too.

My main concern is that we remove the road blocks, now that we have
people interested in contributing to this documentation.

>
> On Wed, May 23, 2018 at 9:56 PM, Frank Kloeker <eumel@arcor.de> wrote:
>
> > Hi Chris,
> >
> > thanks for summarize our session today in Vancouver. As I18n PTL and one
> > of the Docs Core I put Petr in Cc. He is currently Docs PTL, but
> > unfortunatelly not on-site.
> > I couldn't also not get the full history of the story and that's also not
> > the idea to starting finger pointing. As usualy we moving forward and there
> > are some interesting things to know what happened.
> > First of all: There are no "Docs-Team" anymore. If you look at [1] there
> > are mostly part-time contributors like me or people are more involved in
> > other projects and therefore busy. Because of that, the responsibility of
> > documentation content are moved completely to the project teams. Each repo
> > has a user guide, admin guide, deployment guide, and so on. The small
> > Documentation Team provides only tooling and give advices how to write and
> > publish a document. So it's up to you to re-use the old repo on [2] or
> > setup a new one. I would recommend to use the best of both worlds. There
> > are a very good toolset in place for testing and publishing documents.
> > There are also various text editors for rst extensions available, like in
> > vim, notepad++ or also online services. I understand the concerns and when
> > people are sad because their patches are ignored for months. But it's
> > alltime a question of responsibilty and how can spend people time.
> > I would be available for help. As I18n PTL I could imagine that a
> > OpenStack Operations Guide is available in different languages and portable
> > in different formats like in Sphinx. For us as translation team it's a good
> > possibility to get feedback about the quality and to understand the
> > requirements, also for other documents.
> > So let's move on.
> >
> > kind regards
> >
> > Frank
> >
> > [1] https://review.openstack.org/#/admin/groups/30,members
> > [2] https://github.com/openstack/operations-guide
> >
> >
> > Am 2018-05-24 03:38, schrieb Chris Morgan:
> >
> >> Hello Everyone,
> >>
> >> In the Ops Community documentation working session today in Vancouver,
> >> we made some really good progress (etherpad here:
> >> https://etherpad.openstack.org/p/YVR-Ops-Community-Docs but not all of
> >> the good stuff is yet written down).
> >>
> >> In short, we're going to course correct on maintaining the Operators
> >> Guide, the HA Guide and Architecture Guide, not edit-in-place via the
> >> wiki and instead try still maintaining them as code, but with a
> >> different, new set of owners, possibly in a new Ops-focused repo.
> >> There was a strong consensus that a) code workflow >> wiki workflow
> >> and that b) openstack core docs tools are just fine.
> >>
> >> There is a lot still to be decided on how where and when, but we do
> >> have an offer of a rewrite of the HA Guide, as long as the changes
> >> will be allowed to actually land, so we expect to actually start
> >> showing some progress.
> >>
> >> At the end of the session, people wanted to know how to follow along
> >> as various people work out how to do this... and so for now that place
> >> is this very email thread. The idea is if the code for those documents
> >> goes to live in a different repo, or if new contributors turn up, or
> >> if a new version we will announce/discuss it here until such time as
> >> we have a better home for this initiative.
> >>
> >> Cheers
> >>
> >> Chris
> >>
> >> --
> >> Chris Morgan <mihalis68@gmail.com>
> >> _______________________________________________
> >> OpenStack-operators mailing list
> >> OpenStack-operators@lists.openstack.org
> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
> >>
> >
> >
> > _______________________________________________
> > OpenStack-operators mailing list
> > OpenStack-operators@lists.openstack.org
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
> >
>

_______________________________________________
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

Sure definitely, that's why I said I was not trying to detour the
conversation, but rather asking for feedback. Definitely agree things
should continue to plow forward and Chris has been doing an excellent job
here and I think it is awesome that he is continuing to push this.

On Wed, May 23, 2018 at 10:58 PM, Doug Hellmann <doug@doughellmann.com>
wrote:

> Excerpts from Melvin Hillsman's message of 2018-05-23 22:26:02 -0700:
> > Great to see this moving. I have some questions/concerns based on your
> > statement Doug about docs.openstack.org publishing and do not want to
> > detour the conversation but ask for feedback. Currently there are a
> number
>
> I'm just unclear on that, but don't consider it a blocker. We will sort
> out whatever governance or policy change is needed to let this move
> forward.
>
> > of repositories under osops-
> >
> > https://github.com/openstack-infra/project-config/blob/
> master/gerrit/projects.yaml#L5673-L5703
> >
> > Generally active:
> > osops-tools-contrib
> > osops-tools-generic
> > osops-tools-monitoring
> >
> >
> > Probably dead:
> > osops-tools-logging
> > osops-coda
> > osops-example-configs
> >
> > Because you are more familiar with how things work, is there a way to
> > consolidate these vs coming up with another repo like osops-docs or
> > whatever in this case? And second, is there already governance clearance
> to
> > publish based on the following - https://launchpad.net/osops - which is
> > where these repos originated.
>
> I don't really know what any of those things are, or whether it
> makes sense to put this new content there. I assumed we would make
> a repo with a name like "operations-guide", but that's up to Chris
> and John. If they think reusing an existing repository makes sense,
> that would be OK with me, but it's cheap and easy to set up a new
> one, too.
>
> My main concern is that we remove the road blocks, now that we have
> people interested in contributing to this documentation.
>
> >
> > On Wed, May 23, 2018 at 9:56 PM, Frank Kloeker <eumel@arcor.de> wrote:
> >
> > > Hi Chris,
> > >
> > > thanks for summarize our session today in Vancouver. As I18n PTL and
> one
> > > of the Docs Core I put Petr in Cc. He is currently Docs PTL, but
> > > unfortunatelly not on-site.
> > > I couldn't also not get the full history of the story and that's also
> not
> > > the idea to starting finger pointing. As usualy we moving forward and
> there
> > > are some interesting things to know what happened.
> > > First of all: There are no "Docs-Team" anymore. If you look at [1]
> there
> > > are mostly part-time contributors like me or people are more involved
> in
> > > other projects and therefore busy. Because of that, the responsibility
> of
> > > documentation content are moved completely to the project teams. Each
> repo
> > > has a user guide, admin guide, deployment guide, and so on. The small
> > > Documentation Team provides only tooling and give advices how to write
> and
> > > publish a document. So it's up to you to re-use the old repo on [2] or
> > > setup a new one. I would recommend to use the best of both worlds.
> There
> > > are a very good toolset in place for testing and publishing documents.
> > > There are also various text editors for rst extensions available, like
> in
> > > vim, notepad++ or also online services. I understand the concerns and
> when
> > > people are sad because their patches are ignored for months. But it's
> > > alltime a question of responsibilty and how can spend people time.
> > > I would be available for help. As I18n PTL I could imagine that a
> > > OpenStack Operations Guide is available in different languages and
> portable
> > > in different formats like in Sphinx. For us as translation team it's a
> good
> > > possibility to get feedback about the quality and to understand the
> > > requirements, also for other documents.
> > > So let's move on.
> > >
> > > kind regards
> > >
> > > Frank
> > >
> > > [1] https://review.openstack.org/#/admin/groups/30,members
> > > [2] https://github.com/openstack/operations-guide
> > >
> > >
> > > Am 2018-05-24 03:38, schrieb Chris Morgan:
> > >
> > >> Hello Everyone,
> > >>
> > >> In the Ops Community documentation working session today in Vancouver,
> > >> we made some really good progress (etherpad here:
> > >> https://etherpad.openstack.org/p/YVR-Ops-Community-Docs but not all
> of
> > >> the good stuff is yet written down).
> > >>
> > >> In short, we're going to course correct on maintaining the Operators
> > >> Guide, the HA Guide and Architecture Guide, not edit-in-place via the
> > >> wiki and instead try still maintaining them as code, but with a
> > >> different, new set of owners, possibly in a new Ops-focused repo.
> > >> There was a strong consensus that a) code workflow >> wiki workflow
> > >> and that b) openstack core docs tools are just fine.
> > >>
> > >> There is a lot still to be decided on how where and when, but we do
> > >> have an offer of a rewrite of the HA Guide, as long as the changes
> > >> will be allowed to actually land, so we expect to actually start
> > >> showing some progress.
> > >>
> > >> At the end of the session, people wanted to know how to follow along
> > >> as various people work out how to do this... and so for now that place
> > >> is this very email thread. The idea is if the code for those documents
> > >> goes to live in a different repo, or if new contributors turn up, or
> > >> if a new version we will announce/discuss it here until such time as
> > >> we have a better home for this initiative.
> > >>
> > >> Cheers
> > >>
> > >> Chris
> > >>
> > >> --
> > >> Chris Morgan <mihalis68@gmail.com>
> > >> _______________________________________________
> > >> OpenStack-operators mailing list
> > >> OpenStack-operators@lists.openstack.org
> > >> http://lists.openstack.org/cgi-bin/mailman/listinfo/
> openstack-operators
> > >>
> > >
> > >
> > > _______________________________________________
> > > OpenStack-operators mailing list
> > > OpenStack-operators@lists.openstack.org
> > > http://lists.openstack.org/cgi-bin/mailman/listinfo/
> openstack-operators
> > >
> >
>
> _______________________________________________
> OpenStack-operators mailing list
> OpenStack-operators@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>



--
Kind regards,

Melvin Hillsman
mrhillsman@gmail.com
mobile: (832) 264-2646

Excerpts from Doug Hellmann's message of 2018-05-23 22:58:40 -0700:
> Excerpts from Melvin Hillsman's message of 2018-05-23 22:26:02 -0700:
> > Great to see this moving. I have some questions/concerns based on your
> > statement Doug about docs.openstack.org publishing and do not want to
> > detour the conversation but ask for feedback. Currently there are a number
>
> I'm just unclear on that, but don't consider it a blocker. We will sort
> out whatever governance or policy change is needed to let this move
> forward.

When I talked with Petr about it, he pointed to the Security SIG
and Security Guide as a parallel precedent for this. IIRC, yesterday
Adam mentioned that the Self-Healing SIG was also going to be
managing some documentation, so we have two examples.

Looking at https://governance.openstack.org/sigs/, I don't see
another existing SIG that it would make sense to join, so, I think
to deal with the publishing rights we would want set up a SIG for
something like "Operator Documentation," which gives you some
flexibility on exactly what content is managed.

I know you wanted to avoid lots of governance overhead, so I want
to just mention that establishing a SIG is meant to be a painless
and light-weight way to declare that a group of interested people
exists so that others can find them and participate in the work
[1]. It shouldn't take much effort to do the setup, and any ongoing
communication is something you would presumably by doing anyway
among a group of people trying to collaborate on a project like
this.

Let me know if you have any questions or concerns about the process.

Doug

[1] https://governance.openstack.org/sigs/#process-to-create-a-sig

>
> > of repositories under osops-
> >
> > https://github.com/openstack-infra/project-config/blob/master/gerrit/projects.yaml#L5673-L5703
> >
> > Generally active:
> > osops-tools-contrib
> > osops-tools-generic
> > osops-tools-monitoring
> >
> >
> > Probably dead:
> > osops-tools-logging
> > osops-coda
> > osops-example-configs
> >
> > Because you are more familiar with how things work, is there a way to
> > consolidate these vs coming up with another repo like osops-docs or
> > whatever in this case? And second, is there already governance clearance to
> > publish based on the following - https://launchpad.net/osops - which is
> > where these repos originated.
>
> I don't really know what any of those things are, or whether it
> makes sense to put this new content there. I assumed we would make
> a repo with a name like "operations-guide", but that's up to Chris
> and John. If they think reusing an existing repository makes sense,
> that would be OK with me, but it's cheap and easy to set up a new
> one, too.
>
> My main concern is that we remove the road blocks, now that we have
> people interested in contributing to this documentation.
>
> >
> > On Wed, May 23, 2018 at 9:56 PM, Frank Kloeker <eumel@arcor.de> wrote:
> >
> > > Hi Chris,
> > >
> > > thanks for summarize our session today in Vancouver. As I18n PTL and one
> > > of the Docs Core I put Petr in Cc. He is currently Docs PTL, but
> > > unfortunatelly not on-site.
> > > I couldn't also not get the full history of the story and that's also not
> > > the idea to starting finger pointing. As usualy we moving forward and there
> > > are some interesting things to know what happened.
> > > First of all: There are no "Docs-Team" anymore. If you look at [1] there
> > > are mostly part-time contributors like me or people are more involved in
> > > other projects and therefore busy. Because of that, the responsibility of
> > > documentation content are moved completely to the project teams. Each repo
> > > has a user guide, admin guide, deployment guide, and so on. The small
> > > Documentation Team provides only tooling and give advices how to write and
> > > publish a document. So it's up to you to re-use the old repo on [2] or
> > > setup a new one. I would recommend to use the best of both worlds. There
> > > are a very good toolset in place for testing and publishing documents.
> > > There are also various text editors for rst extensions available, like in
> > > vim, notepad++ or also online services. I understand the concerns and when
> > > people are sad because their patches are ignored for months. But it's
> > > alltime a question of responsibilty and how can spend people time.
> > > I would be available for help. As I18n PTL I could imagine that a
> > > OpenStack Operations Guide is available in different languages and portable
> > > in different formats like in Sphinx. For us as translation team it's a good
> > > possibility to get feedback about the quality and to understand the
> > > requirements, also for other documents.
> > > So let's move on.
> > >
> > > kind regards
> > >
> > > Frank
> > >
> > > [1] https://review.openstack.org/#/admin/groups/30,members
> > > [2] https://github.com/openstack/operations-guide
> > >
> > >
> > > Am 2018-05-24 03:38, schrieb Chris Morgan:
> > >
> > >> Hello Everyone,
> > >>
> > >> In the Ops Community documentation working session today in Vancouver,
> > >> we made some really good progress (etherpad here:
> > >> https://etherpad.openstack.org/p/YVR-Ops-Community-Docs but not all of
> > >> the good stuff is yet written down).
> > >>
> > >> In short, we're going to course correct on maintaining the Operators
> > >> Guide, the HA Guide and Architecture Guide, not edit-in-place via the
> > >> wiki and instead try still maintaining them as code, but with a
> > >> different, new set of owners, possibly in a new Ops-focused repo.
> > >> There was a strong consensus that a) code workflow >> wiki workflow
> > >> and that b) openstack core docs tools are just fine.
> > >>
> > >> There is a lot still to be decided on how where and when, but we do
> > >> have an offer of a rewrite of the HA Guide, as long as the changes
> > >> will be allowed to actually land, so we expect to actually start
> > >> showing some progress.
> > >>
> > >> At the end of the session, people wanted to know how to follow along
> > >> as various people work out how to do this... and so for now that place
> > >> is this very email thread. The idea is if the code for those documents
> > >> goes to live in a different repo, or if new contributors turn up, or
> > >> if a new version we will announce/discuss it here until such time as
> > >> we have a better home for this initiative.
> > >>
> > >> Cheers
> > >>
> > >> Chris
> > >>
> > >> --
> > >> Chris Morgan <mihalis68@gmail.com>
> > >> _______________________________________________
> > >> OpenStack-operators mailing list
> > >> OpenStack-operators@lists.openstack.org
> > >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
> > >>
> > >
> > >
> > > _______________________________________________
> > > OpenStack-operators mailing list
> > > OpenStack-operators@lists.openstack.org
> > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
> > >
> >

_______________________________________________
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

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.

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.

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. 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 agree governance can also be a parallel discussion. I don't have
strong opinions there but seems based on participants and content like
a "UC" thing but < shrug />

-Jon

_______________________________________________
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

On Thu, May 24, 2018 at 07:07:10AM -0700, Doug Hellmann wrote:

:I know you wanted to avoid lots of governance overhead, so I want
:to just mention that establishing a SIG is meant to be a painless
:and light-weight way to declare that a group of interested people
:exists so that others can find them and participate in the work
:[1]. It shouldn't take much effort to do the setup, and any ongoing
:communication is something you would presumably by doing anyway
:among a group of people trying to collaborate on a project like
:this.

Yeah I can see SIG as a useful structure too. I'm just more familiar
with UC "teams" because of my personal history.

I do thing SIG -vs- team would impace repo naming, and I'm still going
over creation doc, so I'll let this simmer here at least until YVR lunch
time to see if there's consensus or cotroversy in the potential
contributer community. Lacking either I think I will default to
SIG-ops-docs.

Thanks,
-Jon

:
:Let me know if you have any questions or concerns about the process.
:
:Doug
:
:[1] https://governance.openstack.org/sigs/#process-to-create-a-sig
:
:>
:> > of repositories under osops-
:> >
:> > https://github.com/openstack-infra/project-config/blob/master/gerrit/projects.yaml#L5673-L5703
:> >
:> > Generally active:
:> > osops-tools-contrib
:> > osops-tools-generic
:> > osops-tools-monitoring
:> >
:> >
:> > Probably dead:
:> > osops-tools-logging
:> > osops-coda
:> > osops-example-configs
:> >
:> > Because you are more familiar with how things work, is there a way to
:> > consolidate these vs coming up with another repo like osops-docs or
:> > whatever in this case? And second, is there already governance clearance to
:> > publish based on the following - https://launchpad.net/osops - which is
:> > where these repos originated.
:>
:> I don't really know what any of those things are, or whether it
:> makes sense to put this new content there. I assumed we would make
:> a repo with a name like "operations-guide", but that's up to Chris
:> and John. If they think reusing an existing repository makes sense,
:> that would be OK with me, but it's cheap and easy to set up a new
:> one, too.
:>
:> My main concern is that we remove the road blocks, now that we have
:> people interested in contributing to this documentation.
:>
:> >
:> > On Wed, May 23, 2018 at 9:56 PM, Frank Kloeker <eumel@arcor.de> wrote:
:> >
:> > > Hi Chris,
:> > >
:> > > thanks for summarize our session today in Vancouver. As I18n PTL and one
:> > > of the Docs Core I put Petr in Cc. He is currently Docs PTL, but
:> > > unfortunatelly not on-site.
:> > > I couldn't also not get the full history of the story and that's also not
:> > > the idea to starting finger pointing. As usualy we moving forward and there
:> > > are some interesting things to know what happened.
:> > > First of all: There are no "Docs-Team" anymore. If you look at [1] there
:> > > are mostly part-time contributors like me or people are more involved in
:> > > other projects and therefore busy. Because of that, the responsibility of
:> > > documentation content are moved completely to the project teams. Each repo
:> > > has a user guide, admin guide, deployment guide, and so on. The small
:> > > Documentation Team provides only tooling and give advices how to write and
:> > > publish a document. So it's up to you to re-use the old repo on [2] or
:> > > setup a new one. I would recommend to use the best of both worlds. There
:> > > are a very good toolset in place for testing and publishing documents.
:> > > There are also various text editors for rst extensions available, like in
:> > > vim, notepad++ or also online services. I understand the concerns and when
:> > > people are sad because their patches are ignored for months. But it's
:> > > alltime a question of responsibilty and how can spend people time.
:> > > I would be available for help. As I18n PTL I could imagine that a
:> > > OpenStack Operations Guide is available in different languages and portable
:> > > in different formats like in Sphinx. For us as translation team it's a good
:> > > possibility to get feedback about the quality and to understand the
:> > > requirements, also for other documents.
:> > > So let's move on.
:> > >
:> > > kind regards
:> > >
:> > > Frank
:> > >
:> > > [1] https://review.openstack.org/#/admin/groups/30,members
:> > > [2] https://github.com/openstack/operations-guide
:> > >
:> > >
:> > > Am 2018-05-24 03:38, schrieb Chris Morgan:
:> > >
:> > >> Hello Everyone,
:> > >>
:> > >> In the Ops Community documentation working session today in Vancouver,
:> > >> we made some really good progress (etherpad here:
:> > >> https://etherpad.openstack.org/p/YVR-Ops-Community-Docs but not all of
:> > >> the good stuff is yet written down).
:> > >>
:> > >> In short, we're going to course correct on maintaining the Operators
:> > >> Guide, the HA Guide and Architecture Guide, not edit-in-place via the
:> > >> wiki and instead try still maintaining them as code, but with a
:> > >> different, new set of owners, possibly in a new Ops-focused repo.
:> > >> There was a strong consensus that a) code workflow >> wiki workflow
:> > >> and that b) openstack core docs tools are just fine.
:> > >>
:> > >> There is a lot still to be decided on how where and when, but we do
:> > >> have an offer of a rewrite of the HA Guide, as long as the changes
:> > >> will be allowed to actually land, so we expect to actually start
:> > >> showing some progress.
:> > >>
:> > >> At the end of the session, people wanted to know how to follow along
:> > >> as various people work out how to do this... and so for now that place
:> > >> is this very email thread. The idea is if the code for those documents
:> > >> goes to live in a different repo, or if new contributors turn up, or
:> > >> if a new version we will announce/discuss it here until such time as
:> > >> we have a better home for this initiative.
:> > >>
:> > >> Cheers
:> > >>
:> > >> Chris
:> > >>
:> > >> --
:> > >> Chris Morgan <mihalis68@gmail.com>
:> > >> _______________________________________________
:> > >> OpenStack-operators mailing list
:> > >> OpenStack-operators@lists.openstack.org
:> > >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
:> > >>
:> > >
:> > >
:> > > _______________________________________________
:> > > OpenStack-operators mailing list
:> > > OpenStack-operators@lists.openstack.org
:> > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
:> > >
:> >
:
:_______________________________________________
:OpenStack-operators mailing list
:OpenStack-operators@lists.openstack.org
:http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

_______________________________________________
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

I think a great model we have in general as a community is if people show
up to do the work, it is not something crazy, get out of their way; at
least that is how I think of it. I apologize if there is any perception
opposed to my previous statement by me bringing up the other repos. I tried
to be clear in wanting to get feedback from Doug in hope that as we move
forward in general, what are some thoughts on that front to ensure we
continue to remove roadblocks if any exist in parallel to great work, like
what Chris is driving here. On that front, please do what works best for
those doing the work.

On Thu, May 24, 2018 at 7:26 AM, Jonathan D. Proulx <jon@csail.mit.edu>
wrote:

> On Thu, May 24, 2018 at 07:07:10AM -0700, Doug Hellmann wrote:
>
> :I know you wanted to avoid lots of governance overhead, so I want
> :to just mention that establishing a SIG is meant to be a painless
> :and light-weight way to declare that a group of interested people
> :exists so that others can find them and participate in the work
> :[1]. It shouldn't take much effort to do the setup, and any ongoing
> :communication is something you would presumably by doing anyway
> :among a group of people trying to collaborate on a project like
> :this.
>
> Yeah I can see SIG as a useful structure too. I'm just more familiar
> with UC "teams" because of my personal history.
>
> I do thing SIG -vs- team would impace repo naming, and I'm still going
> over creation doc, so I'll let this simmer here at least until YVR lunch
> time to see if there's consensus or cotroversy in the potential
> contributer community. Lacking either I think I will default to
> SIG-ops-docs.
>
> Thanks,
> -Jon
>
> :
> :Let me know if you have any questions or concerns about the process.
> :
> :Doug
> :
> :[1] https://governance.openstack.org/sigs/#process-to-create-a-sig
> :
> :>
> :> > of repositories under osops-
> :> >
> :> > https://github.com/openstack-infra/project-config/blob/
> master/gerrit/projects.yaml#L5673-L5703
> :> >
> :> > Generally active:
> :> > osops-tools-contrib
> :> > osops-tools-generic
> :> > osops-tools-monitoring
> :> >
> :> >
> :> > Probably dead:
> :> > osops-tools-logging
> :> > osops-coda
> :> > osops-example-configs
> :> >
> :> > Because you are more familiar with how things work, is there a way to
> :> > consolidate these vs coming up with another repo like osops-docs or
> :> > whatever in this case? And second, is there already governance
> clearance to
> :> > publish based on the following - https://launchpad.net/osops - which
> is
> :> > where these repos originated.
> :>
> :> I don't really know what any of those things are, or whether it
> :> makes sense to put this new content there. I assumed we would make
> :> a repo with a name like "operations-guide", but that's up to Chris
> :> and John. If they think reusing an existing repository makes sense,
> :> that would be OK with me, but it's cheap and easy to set up a new
> :> one, too.
> :>
> :> My main concern is that we remove the road blocks, now that we have
> :> people interested in contributing to this documentation.
> :>
> :> >
> :> > On Wed, May 23, 2018 at 9:56 PM, Frank Kloeker <eumel@arcor.de>
> wrote:
> :> >
> :> > > Hi Chris,
> :> > >
> :> > > thanks for summarize our session today in Vancouver. As I18n PTL
> and one
> :> > > of the Docs Core I put Petr in Cc. He is currently Docs PTL, but
> :> > > unfortunatelly not on-site.
> :> > > I couldn't also not get the full history of the story and that's
> also not
> :> > > the idea to starting finger pointing. As usualy we moving forward
> and there
> :> > > are some interesting things to know what happened.
> :> > > First of all: There are no "Docs-Team" anymore. If you look at [1]
> there
> :> > > are mostly part-time contributors like me or people are more
> involved in
> :> > > other projects and therefore busy. Because of that, the
> responsibility of
> :> > > documentation content are moved completely to the project teams.
> Each repo
> :> > > has a user guide, admin guide, deployment guide, and so on. The
> small
> :> > > Documentation Team provides only tooling and give advices how to
> write and
> :> > > publish a document. So it's up to you to re-use the old repo on [2]
> or
> :> > > setup a new one. I would recommend to use the best of both worlds.
> There
> :> > > are a very good toolset in place for testing and publishing
> documents.
> :> > > There are also various text editors for rst extensions available,
> like in
> :> > > vim, notepad++ or also online services. I understand the concerns
> and when
> :> > > people are sad because their patches are ignored for months. But
> it's
> :> > > alltime a question of responsibilty and how can spend people time.
> :> > > I would be available for help. As I18n PTL I could imagine that a
> :> > > OpenStack Operations Guide is available in different languages and
> portable
> :> > > in different formats like in Sphinx. For us as translation team
> it's a good
> :> > > possibility to get feedback about the quality and to understand the
> :> > > requirements, also for other documents.
> :> > > So let's move on.
> :> > >
> :> > > kind regards
> :> > >
> :> > > Frank
> :> > >
> :> > > [1] https://review.openstack.org/#/admin/groups/30,members
> :> > > [2] https://github.com/openstack/operations-guide
> :> > >
> :> > >
> :> > > Am 2018-05-24 03:38, schrieb Chris Morgan:
> :> > >
> :> > >> Hello Everyone,
> :> > >>
> :> > >> In the Ops Community documentation working session today in
> Vancouver,
> :> > >> we made some really good progress (etherpad here:
> :> > >> https://etherpad.openstack.org/p/YVR-Ops-Community-Docs but not
> all of
> :> > >> the good stuff is yet written down).
> :> > >>
> :> > >> In short, we're going to course correct on maintaining the
> Operators
> :> > >> Guide, the HA Guide and Architecture Guide, not edit-in-place via
> the
> :> > >> wiki and instead try still maintaining them as code, but with a
> :> > >> different, new set of owners, possibly in a new Ops-focused repo.
> :> > >> There was a strong consensus that a) code workflow >> wiki workflow
> :> > >> and that b) openstack core docs tools are just fine.
> :> > >>
> :> > >> There is a lot still to be decided on how where and when, but we do
> :> > >> have an offer of a rewrite of the HA Guide, as long as the changes
> :> > >> will be allowed to actually land, so we expect to actually start
> :> > >> showing some progress.
> :> > >>
> :> > >> At the end of the session, people wanted to know how to follow
> along
> :> > >> as various people work out how to do this... and so for now that
> place
> :> > >> is this very email thread. The idea is if the code for those
> documents
> :> > >> goes to live in a different repo, or if new contributors turn up,
> or
> :> > >> if a new version we will announce/discuss it here until such time
> as
> :> > >> we have a better home for this initiative.
> :> > >>
> :> > >> Cheers
> :> > >>
> :> > >> Chris
> :> > >>
> :> > >> --
> :> > >> Chris Morgan <mihalis68@gmail.com>
> :> > >> _______________________________________________
> :> > >> OpenStack-operators mailing list
> :> > >> OpenStack-operators@lists.openstack.org
> :> > >> http://lists.openstack.org/cgi-bin/mailman/listinfo/
> openstack-operators
> :> > >>
> :> > >
> :> > >
> :> > > _______________________________________________
> :> > > OpenStack-operators mailing list
> :> > > OpenStack-operators@lists.openstack.org
> :> > > http://lists.openstack.org/cgi-bin/mailman/listinfo/
> openstack-operators
> :> > >
> :> >
> :
> :_______________________________________________
> :OpenStack-operators mailing list
> :OpenStack-operators@lists.openstack.org
> :http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>
> _______________________________________________
> OpenStack-operators mailing list
> OpenStack-operators@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>



--
Kind regards,

Melvin Hillsman
mrhillsman@gmail.com
mobile: (832) 264-2646

On Thu, May 24, 2018 at 01:26:07PM -0700, Melvin Hillsman wrote:
: I think a great model we have in general as a community is if people
: show up to do the work, it is not something crazy, get out of their
: way; at least that is how I think of it. I apologize if there is any
: perception opposed to my previous statement by me bringing up the other
: repos. I tried to be clear in wanting to get feedback from Doug in hope
: that as we move forward in general, what are some thoughts on that
: front to ensure we continue to remove roadblocks if any exist in
: parallel to great work, like what Chris is driving here. On that front,
: please do what works best for those doing the work.

No worries I feel the love :)

Going to go forward implemnting as SIG + repo which seems lightest way
forward, we can always adapt and evolve.

-Jon

: On Thu, May 24, 2018 at 7:26 AM, Jonathan D. Proulx
: <[1]jon@csail.mit.edu> wrote:
:
: On Thu, May 24, 2018 at 07:07:10AM -0700, Doug Hellmann wrote:
: :I know you wanted to avoid lots of governance overhead, so I want
: :to just mention that establishing a SIG is meant to be a painless
: :and light-weight way to declare that a group of interested people
: :exists so that others can find them and participate in the work
: :[1]. It shouldn't take much effort to do the setup, and any ongoing
: :communication is something you would presumably by doing anyway
: :among a group of people trying to collaborate on a project like
: :this.
: Yeah I can see SIG as a useful structure too. I'm just more
: familiar
: with UC "teams" because of my personal history.
: I do thing SIG -vs- team would impace repo naming, and I'm still
: going
: over creation doc, so I'll let this simmer here at least until YVR
: lunch
: time to see if there's consensus or cotroversy in the potential
: contributer community. Lacking either I think I will default to
: SIG-ops-docs.
: Thanks,
: -Jon
: :
: :Let me know if you have any questions or concerns about the
: process.
:
: :
: :Doug
: :
: :[1] [2]https://governance.openstack.org/sigs/#process-to-create-a-sig
: :
: :>
: :> > of repositories under osops-
: :> >
: :> > [3]https://github.com/openstack-infra/project-config/blob/
: master/gerrit/projects.yaml#L5673-L5703
: :> >
: :> > Generally active:
: :> > osops-tools-contrib
: :> > osops-tools-generic
: :> > osops-tools-monitoring
: :> >
: :> >
: :> > Probably dead:
: :> > osops-tools-logging
: :> > osops-coda
: :> > osops-example-configs
: :> >
: :> > Because you are more familiar with how things work, is there a way
: to
: :> > consolidate these vs coming up with another repo like osops-docs
: or
: :> > whatever in this case? And second, is there already governance
: clearance to
: :> > publish based on the following - [4]https://launchpad.net/osops -
: which is
: :> > where these repos originated.
: :>
: :> I don't really know what any of those things are, or whether it
: :> makes sense to put this new content there. I assumed we would make
: :> a repo with a name like "operations-guide", but that's up to Chris
: :> and John. If they think reusing an existing repository makes sense,
: :> that would be OK with me, but it's cheap and easy to set up a new
: :> one, too.
: :>
: :> My main concern is that we remove the road blocks, now that we have
: :> people interested in contributing to this documentation.
: :>
: :> >
: :> > On Wed, May 23, 2018 at 9:56 PM, Frank Kloeker <[5]eumel@arcor.de>
: wrote:
: :> >
: :> > > Hi Chris,
: :> > >
: :> > > thanks for summarize our session today in Vancouver. As I18n PTL
: and one
: :> > > of the Docs Core I put Petr in Cc. He is currently Docs PTL, but
: :> > > unfortunatelly not on-site.
: :> > > I couldn't also not get the full history of the story and that's
: also not
: :> > > the idea to starting finger pointing. As usualy we moving
: forward and there
: :> > > are some interesting things to know what happened.
: :> > > First of all: There are no "Docs-Team" anymore. If you look at
: [1] there
: :> > > are mostly part-time contributors like me or people are more
: involved in
: :> > > other projects and therefore busy. Because of that, the
: responsibility of
: :> > > documentation content are moved completely to the project teams.
: Each repo
: :> > > has a user guide, admin guide, deployment guide, and so on. The
: small
: :> > > Documentation Team provides only tooling and give advices how to
: write and
: :> > > publish a document. So it's up to you to re-use the old repo on
: [2] or
: :> > > setup a new one. I would recommend to use the best of both
: worlds. There
: :> > > are a very good toolset in place for testing and publishing
: documents.
: :> > > There are also various text editors for rst extensions
: available, like in
: :> > > vim, notepad++ or also online services. I understand the
: concerns and when
: :> > > people are sad because their patches are ignored for months. But
: it's
: :> > > alltime a question of responsibilty and how can spend people
: time.
: :> > > I would be available for help. As I18n PTL I could imagine that
: a
: :> > > OpenStack Operations Guide is available in different languages
: and portable
: :> > > in different formats like in Sphinx. For us as translation team
: it's a good
: :> > > possibility to get feedback about the quality and to understand
: the
: :> > > requirements, also for other documents.
: :> > > So let's move on.
: :> > >
: :> > > kind regards
: :> > >
: :> > > Frank
: :> > >
: :> > > [1] [6]https://review.openstack.org/#/admin/groups/30,members
: :> > > [2] [7]https://github.com/openstack/operations-guide
: :> > >
: :> > >
: :> > > Am 2018-05-24 03:38, schrieb Chris Morgan:
: :> > >
: :> > >> Hello Everyone,
: :> > >>
: :> > >> In the Ops Community documentation working session today in
: Vancouver,
: :> > >> we made some really good progress (etherpad here:
: :> > >> [8]https://etherpad.openstack.org/p/YVR-Ops-Community-Docs but
: not all of
: :> > >> the good stuff is yet written down).
: :> > >>
: :> > >> In short, we're going to course correct on maintaining the
: Operators
: :> > >> Guide, the HA Guide and Architecture Guide, not edit-in-place
: via the
: :> > >> wiki and instead try still maintaining them as code, but with a
: :> > >> different, new set of owners, possibly in a new Ops-focused
: repo.
: :> > >> There was a strong consensus that a) code workflow >> wiki
: workflow
: :> > >> and that b) openstack core docs tools are just fine.
: :> > >>
: :> > >> There is a lot still to be decided on how where and when, but
: we do
: :> > >> have an offer of a rewrite of the HA Guide, as long as the
: changes
: :> > >> will be allowed to actually land, so we expect to actually
: start
: :> > >> showing some progress.
: :> > >>
: :> > >> At the end of the session, people wanted to know how to follow
: along
: :> > >> as various people work out how to do this... and so for now
: that place
: :> > >> is this very email thread. The idea is if the code for those
: documents
: :> > >> goes to live in a different repo, or if new contributors turn
: up, or
: :> > >> if a new version we will announce/discuss it here until such
: time as
: :> > >> we have a better home for this initiative.
: :> > >>
: :> > >> Cheers
: :> > >>
: :> > >> Chris
: :> > >>
: :> > >> --
: :> > >> Chris Morgan <[9]mihalis68@gmail.com>
: :> > >> _______________________________________________
: :> > >> OpenStack-operators mailing list
: :> > >> [10]OpenStack-operators@lists.openstack.org
: :> > >> [11]http://lists.openstack.org/cgi-bin/mailman/listinfo/
: openstack-operators
: :> > >>
: :> > >
: :> > >
: :> > > _______________________________________________
: :> > > OpenStack-operators mailing list
: :> > > [12]OpenStack-operators@lists.openstack.org
: :> > > [13]http://lists.openstack.org/cgi-bin/mailman/listinfo/
: openstack-operators
: :> > >
: :> >
: :
: :_______________________________________________
: :OpenStack-operators mailing list
: :[14]OpenStack-operators@lists.openstack.org
: :[15]http://lists.openstack.org/cgi-bin/mailman/listinfo/
: openstack-operators
: _______________________________________________
: OpenStack-operators mailing list
: [16]OpenStack-operators@lists.openstack.org
: [17]http://lists.openstack.org/cgi-bin/mailman/listinfo/
: openstack-operators
:
: --
: Kind regards,
: Melvin Hillsman
: [18]mrhillsman@gmail.com
: mobile: (832) 264-2646
:
:References
:
: 1. mailto:jon@csail.mit.edu
: 2. https://governance.openstack.org/sigs/#process-to-create-a-sig
: 3. https://github.com/openstack-infra/project-config/blob/master/gerrit/projects.yaml#L5673-L5703
: 4. https://launchpad.net/osops
: 5. mailto:eumel@arcor.de
: 6. https://review.openstack.org/#/admin/groups/30,members
: 7. https://github.com/openstack/operations-guide
: 8. https://etherpad.openstack.org/p/YVR-Ops-Community-Docs
: 9. mailto:mihalis68@gmail.com
: 10. mailto:OpenStack-operators@lists.openstack.org
: 11. http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
: 12. mailto:OpenStack-operators@lists.openstack.org
: 13. http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
: 14. mailto:OpenStack-operators@lists.openstack.org
: 15. http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
: 16. mailto:OpenStack-operators@lists.openstack.org
: 17. http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
: 18. mailto:mrhillsman@gmail.com

_______________________________________________
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

Excerpts from Jonathan D. Proulx's message of 2018-05-24 07:19:29 -0700:
>
> 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.

Normally I would say "yay, consistency!" In this case, let's verify
that that name isn't going to have an undesirable effect when the
content is published.

I know the default destination directory for the publish job is
taken from the repository name, which would mean we would have a
URL like docs.openstack.org/osops-docs. I don't know if there is a
way to override that, but the infra team will know. So, if you want
a URL like docs.o.o/operations-guide instead, you'll want to check
with the infra folks before creating the repo to make sure it's set
up in a way to get the URL you want.

Doug

_______________________________________________
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

On May 25, 2018 5:30:40 AM PDT, Doug Hellmann <doug@doughellmann.com> wrote:
>Excerpts from Jonathan D. Proulx's message of 2018-05-24 07:19:29
>-0700:
>>
>> 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.
>
>Normally I would say "yay, consistency!" In this case, let's verify
>that that name isn't going to have an undesirable effect when the
>content is published.
>
>I know the default destination directory for the publish job is
>taken from the repository name, which would mean we would have a
>URL like docs.openstack.org/osops-docs. I don't know if there is a
>way to override that, but the infra team will know. So, if you want
>a URL like docs.o.o/operations-guide instead, you'll want to check
>with the infra folks before creating the repo to make sure it's set
>up in a way to get the URL you want.

Names are hard! Thanks for pointing out the implications.

-Jon

--
Sent from my Android device with K-9 Mail. Please excuse my brevity.

_______________________________________________
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

On Thu, 24 May 2018 07:19:29 -0700
"Jonathan D. Proulx" <jon@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

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.

> 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.

> 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.

> 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.

Cheers,
pk

_______________________________________________
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

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@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
>

_______________________________________________
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

Reviving this thread with a fresh start. See below for the original.

To recap, the ops community is willing to take over some of the operator
documentation that is no longer available due to the loss of documentation team
resources. From discussions, there needs to be some official governance over
this operator owned repo (or repos) so it is recommended that a sig be formed.
The repos can be created in the meantime, but consideration needs to be taken
about naming as by default, the repo name is what is reflected in the
documentation publishing location.

SIG Formation
-------------
There were a couple suggestions on naming and focus for this sig, but I would
like to make a slightly different proposal. I would actually like to see a
sig-operator group formed. We have repos for operator tools and other useful
things and we have a mix of operators, vendors, and others that work together
on things like the ops meetup. I think it would make sense to make this into an
official SIG that could have a broader scope than just documentation.

Docs Repos
----------
Doug made a good suggestion that we may want these things published under
something like docs.openstack.org/operations-guide. So based on this, I think
for now at least we should create an opestack/operations-guide repo that will
end up being owned by this SIG. I would expect most documentation generated or
owned by this group would just be located somewhere under that repo, but if the
need arises we can add additional repos.

There are other ops repos out there right now. I would expect the ownership of
those to move under this sig as well, but that is a seperate and less pressing
concern at this point.

Bug Tracking
------------
There should be some way to track tasks and needs for this documentation and
any other repos that are moved under this sig. Since it is the currently
planned direction for all OpenStack projects (or at least there is a vocal
desire for it to be) I think a Storyboard project should be created for this
SIG's activities.

Plan
----
So to recap above, I would propose the following actions be taken:

1. Create sig-operators as a group to manage operator efforts at least related
to what needs to be done in repos.
2. Create an openstack/operations-guide repo to be the new home of the
operations documentation.
3. Create a new StoryBoard project to help track work in these repos
x. Document all this.
9. Profit!

I'm willing to work through the steps to get these things set up. Please give
feedback if this proposed plan makes sense or if there is anything different
that would be preferred.

Thanks,
Sean

On Wed, May 23, 2018 at 06:38:32PM -0700, Chris Morgan wrote:
> Hello Everyone,
>
> In the Ops Community documentation working session today in Vancouver, we
> made some really good progress (etherpad here:
> https://etherpad.openstack.org/p/YVR-Ops-Community-Docs but not all of the
> good stuff is yet written down).
>
> In short, we're going to course correct on maintaining the Operators Guide,
> the HA Guide and Architecture Guide, not edit-in-place via the wiki and
> instead try still maintaining them as code, but with a different, new set
> of owners, possibly in a new Ops-focused repo. There was a strong consensus
> that a) code workflow >> wiki workflow and that b) openstack core docs
> tools are just fine.
>
> There is a lot still to be decided on how where and when, but we do have an
> offer of a rewrite of the HA Guide, as long as the changes will be allowed
> to actually land, so we expect to actually start showing some progress.
>
> At the end of the session, people wanted to know how to follow along as
> various people work out how to do this... and so for now that place is this
> very email thread. The idea is if the code for those documents goes to live
> in a different repo, or if new contributors turn up, or if a new version we
> will announce/discuss it here until such time as we have a better home for
> this initiative.
>
> Cheers
>
> Chris
>
> --
> Chris Morgan <mihalis68@gmail.com>

> _______________________________________________
> OpenStack-operators mailing list
> OpenStack-operators@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators


_______________________________________________
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

This sounds great. As I understand it Sean can set up a skeleton for us to
work on ops docs (and maybe other things later) with a minimum of
initiation energy. Count me in.

Chris

On Tue, Jun 26, 2018 at 12:42 PM Sean McGinnis <sean.mcginnis@gmx.com>
wrote:

> Reviving this thread with a fresh start. See below for the original.
>
> To recap, the ops community is willing to take over some of the operator
> documentation that is no longer available due to the loss of documentation
> team
> resources. From discussions, there needs to be some official governance
> over
> this operator owned repo (or repos) so it is recommended that a sig be
> formed.
> The repos can be created in the meantime, but consideration needs to be
> taken
> about naming as by default, the repo name is what is reflected in the
> documentation publishing location.
>
> SIG Formation
> -------------
> There were a couple suggestions on naming and focus for this sig, but I
> would
> like to make a slightly different proposal. I would actually like to see a
> sig-operator group formed. We have repos for operator tools and other
> useful
> things and we have a mix of operators, vendors, and others that work
> together
> on things like the ops meetup. I think it would make sense to make this
> into an
> official SIG that could have a broader scope than just documentation.
>
> Docs Repos
> ----------
> Doug made a good suggestion that we may want these things published under
> something like docs.openstack.org/operations-guide. So based on this, I
> think
> for now at least we should create an opestack/operations-guide repo that
> will
> end up being owned by this SIG. I would expect most documentation
> generated or
> owned by this group would just be located somewhere under that repo, but
> if the
> need arises we can add additional repos.
>
> There are other ops repos out there right now. I would expect the
> ownership of
> those to move under this sig as well, but that is a seperate and less
> pressing
> concern at this point.
>
> Bug Tracking
> ------------
> There should be some way to track tasks and needs for this documentation
> and
> any other repos that are moved under this sig. Since it is the currently
> planned direction for all OpenStack projects (or at least there is a vocal
> desire for it to be) I think a Storyboard project should be created for
> this
> SIG's activities.
>
> Plan
> ----
> So to recap above, I would propose the following actions be taken:
>
> 1. Create sig-operators as a group to manage operator efforts at least
> related
> to what needs to be done in repos.
> 2. Create an openstack/operations-guide repo to be the new home of the
> operations documentation.
> 3. Create a new StoryBoard project to help track work in these repos
> x. Document all this.
> 9. Profit!
>
> I'm willing to work through the steps to get these things set up. Please
> give
> feedback if this proposed plan makes sense or if there is anything
> different
> that would be preferred.
>
> Thanks,
> Sean
>
> On Wed, May 23, 2018 at 06:38:32PM -0700, Chris Morgan wrote:
> > Hello Everyone,
> >
> > In the Ops Community documentation working session today in Vancouver, we
> > made some really good progress (etherpad here:
> > https://etherpad.openstack.org/p/YVR-Ops-Community-Docs but not all of
> the
> > good stuff is yet written down).
> >
> > In short, we're going to course correct on maintaining the Operators
> Guide,
> > the HA Guide and Architecture Guide, not edit-in-place via the wiki and
> > instead try still maintaining them as code, but with a different, new set
> > of owners, possibly in a new Ops-focused repo. There was a strong
> consensus
> > that a) code workflow >> wiki workflow and that b) openstack core docs
> > tools are just fine.
> >
> > There is a lot still to be decided on how where and when, but we do have
> an
> > offer of a rewrite of the HA Guide, as long as the changes will be
> allowed
> > to actually land, so we expect to actually start showing some progress.
> >
> > At the end of the session, people wanted to know how to follow along as
> > various people work out how to do this... and so for now that place is
> this
> > very email thread. The idea is if the code for those documents goes to
> live
> > in a different repo, or if new contributors turn up, or if a new version
> we
> > will announce/discuss it here until such time as we have a better home
> for
> > this initiative.
> >
> > Cheers
> >
> > Chris
> >
> > --
> > Chris Morgan <mihalis68@gmail.com>
>
> > _______________________________________________
> > OpenStack-operators mailing list
> > OpenStack-operators@lists.openstack.org
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>
>

--
Chris Morgan <mihalis68@gmail.com>

>
> Plan
> ----
> So to recap above, I would propose the following actions be taken:
>
> 1. Create sig-operators as a group to manage operator efforts at least related
> to what needs to be done in repos.
> 2. Create an openstack/operations-guide repo to be the new home of the
> operations documentation.

One correction to this - that repo already exists. It has been retired, so I
think the action here would just be to "un-retire" the repo and get things
updated to start publishing again.

> 3. Create a new StoryBoard project to help track work in these repos
> x. Document all this.
> 9. Profit!
>
> I'm willing to work through the steps to get these things set up. Please give
> feedback if this proposed plan makes sense or if there is anything different
> that would be preferred.

_______________________________________________
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

On Tue, 26 Jun 2018 12:36:52 -0500
Sean McGinnis <sean.mcginnis-KK0ffGbhmjU@public.gmane.org> wrote:

> >
> > Plan
> > ----
> > So to recap above, I would propose the following actions be taken:
> >
> > 1. Create sig-operators as a group to manage operator efforts at least related
> > to what needs to be done in repos.
> > 2. Create an openstack/operations-guide repo to be the new home of the
> > operations documentation.
>
> One correction to this - that repo already exists. It has been retired, so I
> think the action here would just be to "un-retire" the repo and get things
> updated to start publishing again.

That's great, looks like most of the skeleton from
https://github.com/openstack/operations-guide/tree/c628640944c9de139b4bc9dee80885060d4b6f83
can just be reused.

For step 2, let's start with moving
https://github.com/openstack/openstack-manuals/tree/a1f1748478125ccd68d90a98ccc06c7ec359d3a0/doc/ops-guide
from openstack-manuals, then. Other guides like ha or architecture can live
in their own repos, if the new SIG wants to own them, or can be merged
into the operations guide later on.

> > 3. Create a new StoryBoard project to help track work in these repos
> > x. Document all this.
> > 9. Profit!
> >
> > I'm willing to work through the steps to get these things set up. Please give
> > feedback if this proposed plan makes sense or if there is anything different
> > that would be preferred.

Thanks for the recap and for your help, Sean. If you need help from the
docs team side, please let me know / CC me on your patches.

Cheers,
pk

_______________________________________________
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

Sean put together some really great things here and I do think the SiG
might be the way to go as far as ownership for the repos and the plan looks
pretty complete. I've offered to do the Git and Gerrit Lunch and Learn at
the OPS mmetup if needed to help get folks set up and going.

Amy (spotz)

On Tue, Jun 26, 2018 at 11:42 AM, Sean McGinnis <sean.mcginnis@gmx.com>
wrote:

> Reviving this thread with a fresh start. See below for the original.
>
> To recap, the ops community is willing to take over some of the operator
> documentation that is no longer available due to the loss of documentation
> team
> resources. From discussions, there needs to be some official governance
> over
> this operator owned repo (or repos) so it is recommended that a sig be
> formed.
> The repos can be created in the meantime, but consideration needs to be
> taken
> about naming as by default, the repo name is what is reflected in the
> documentation publishing location.
>
> SIG Formation
> -------------
> There were a couple suggestions on naming and focus for this sig, but I
> would
> like to make a slightly different proposal. I would actually like to see a
> sig-operator group formed. We have repos for operator tools and other
> useful
> things and we have a mix of operators, vendors, and others that work
> together
> on things like the ops meetup. I think it would make sense to make this
> into an
> official SIG that could have a broader scope than just documentation.
>
> Docs Repos
> ----------
> Doug made a good suggestion that we may want these things published under
> something like docs.openstack.org/operations-guide. So based on this, I
> think
> for now at least we should create an opestack/operations-guide repo that
> will
> end up being owned by this SIG. I would expect most documentation
> generated or
> owned by this group would just be located somewhere under that repo, but
> if the
> need arises we can add additional repos.
>
> There are other ops repos out there right now. I would expect the
> ownership of
> those to move under this sig as well, but that is a seperate and less
> pressing
> concern at this point.
>
> Bug Tracking
> ------------
> There should be some way to track tasks and needs for this documentation
> and
> any other repos that are moved under this sig. Since it is the currently
> planned direction for all OpenStack projects (or at least there is a vocal
> desire for it to be) I think a Storyboard project should be created for
> this
> SIG's activities.
>
> Plan
> ----
> So to recap above, I would propose the following actions be taken:
>
> 1. Create sig-operators as a group to manage operator efforts at least
> related
> to what needs to be done in repos.
> 2. Create an openstack/operations-guide repo to be the new home of the
> operations documentation.
> 3. Create a new StoryBoard project to help track work in these repos
> x. Document all this.
> 9. Profit!
>
> I'm willing to work through the steps to get these things set up. Please
> give
> feedback if this proposed plan makes sense or if there is anything
> different
> that would be preferred.
>
> Thanks,
> Sean
>
> On Wed, May 23, 2018 at 06:38:32PM -0700, Chris Morgan wrote:
> > Hello Everyone,
> >
> > In the Ops Community documentation working session today in Vancouver, we
> > made some really good progress (etherpad here:
> > https://etherpad.openstack.org/p/YVR-Ops-Community-Docs but not all of
> the
> > good stuff is yet written down).
> >
> > In short, we're going to course correct on maintaining the Operators
> Guide,
> > the HA Guide and Architecture Guide, not edit-in-place via the wiki and
> > instead try still maintaining them as code, but with a different, new set
> > of owners, possibly in a new Ops-focused repo. There was a strong
> consensus
> > that a) code workflow >> wiki workflow and that b) openstack core docs
> > tools are just fine.
> >
> > There is a lot still to be decided on how where and when, but we do have
> an
> > offer of a rewrite of the HA Guide, as long as the changes will be
> allowed
> > to actually land, so we expect to actually start showing some progress.
> >
> > At the end of the session, people wanted to know how to follow along as
> > various people work out how to do this... and so for now that place is
> this
> > very email thread. The idea is if the code for those documents goes to
> live
> > in a different repo, or if new contributors turn up, or if a new version
> we
> > will announce/discuss it here until such time as we have a better home
> for
> > this initiative.
> >
> > Cheers
> >
> > Chris
> >
> > --
> > Chris Morgan <mihalis68@gmail.com>
>
> > _______________________________________________
> > OpenStack-operators mailing list
> > OpenStack-operators@lists.openstack.org
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>
>
> _______________________________________________
> OpenStack-operators mailing list
> OpenStack-operators@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>

> > Plan
> > ----
> > So to recap above, I would propose the following actions be taken:
> >
> > 1. Create sig-operators as a group to manage operator efforts at least related
> > to what needs to be done in repos.
> > 2. Create an openstack/operations-guide repo to be the new home of the
> > operations documentation.
>
> One correction to this - that repo already exists. It has been retired, so I
> think the action here would just be to "un-retire" the repo and get things
> updated to start publishing again.
>
> > 3. Create a new StoryBoard project to help track work in these repos

Update on progress for this:

Step 1
------

For step 1, the reason for creating a SIG is there is a policy that anything
publishing to docs.openstack.org is owned by some sort of official team. I had
proposed an Operator SIG (https://review.openstack.org/578408) but Thierry
rightly points out that the scope of the way I proposed it is perhaps a little
too broad. I wanted to leave room for ownership of other non-documentation
efforts, but perhaps that is not the best plan.

I can change that, but I think the better approach right now is just to see if
the UC is willing to be the owners of this repo since they are already the
owners for a few others:

http://git.openstack.org/cgit/openstack/governance/tree/reference/user-committee-repos.yaml#n14

I will propose that soon.

Step 2
------

I have gone through the infra steps to unretire the openstack/operations-guide
repo and set up docs build jobs to run on proposed patches and a publishing job
to publish merged patches to docs.openstack.org. That should give us
https://docs.openstack.org/operations-guide/ once we merge an update.

I've also restored the content by pulling the latest out of the
openstack-manuals repo just prior to when it was removed. Sorry, but I was not
able to preserve the git history for all of it, but I do not the source of the
content in the commit message:

https://review.openstack.org/578946

We've updated the "core" group that has rights to merge patches for that repo
and Melvin has sent out an email to see if any of the existing members still
want to be involved. Hopefully we can regrow that list over time.

Step 3
------

I do still need to look into the StoryBoard project creation. This is lower
priority than the other tasks, but I will try to get to this step soon.

Thanks,
Sean


_______________________________________________
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

Hi All...

I'm still a little confused by the state of this :)

I know I made some promises then got distracted the looks like Sean
stepped up and got things a bit further, but where is it now? Do we
have an active repo?

It would be nice to have the repo in place before OPs meetup.

-Jon

On Tue, Jun 26, 2018 at 07:40:33PM -0500, Amy Marrich wrote:
:Sean put together some really great things here and I do think the SiG
:might be the way to go as far as ownership for the repos and the plan looks
:pretty complete. I've offered to do the Git and Gerrit Lunch and Learn at
:the OPS mmetup if needed to help get folks set up and going.
:
:Amy (spotz)
:
:On Tue, Jun 26, 2018 at 11:42 AM, Sean McGinnis <sean.mcginnis@gmx.com>
:wrote:
:
:> Reviving this thread with a fresh start. See below for the original.
:>
:> To recap, the ops community is willing to take over some of the operator
:> documentation that is no longer available due to the loss of documentation
:> team
:> resources. From discussions, there needs to be some official governance
:> over
:> this operator owned repo (or repos) so it is recommended that a sig be
:> formed.
:> The repos can be created in the meantime, but consideration needs to be
:> taken
:> about naming as by default, the repo name is what is reflected in the
:> documentation publishing location.
:>
:> SIG Formation
:> -------------
:> There were a couple suggestions on naming and focus for this sig, but I
:> would
:> like to make a slightly different proposal. I would actually like to see a
:> sig-operator group formed. We have repos for operator tools and other
:> useful
:> things and we have a mix of operators, vendors, and others that work
:> together
:> on things like the ops meetup. I think it would make sense to make this
:> into an
:> official SIG that could have a broader scope than just documentation.
:>
:> Docs Repos
:> ----------
:> Doug made a good suggestion that we may want these things published under
:> something like docs.openstack.org/operations-guide. So based on this, I
:> think
:> for now at least we should create an opestack/operations-guide repo that
:> will
:> end up being owned by this SIG. I would expect most documentation
:> generated or
:> owned by this group would just be located somewhere under that repo, but
:> if the
:> need arises we can add additional repos.
:>
:> There are other ops repos out there right now. I would expect the
:> ownership of
:> those to move under this sig as well, but that is a seperate and less
:> pressing
:> concern at this point.
:>
:> Bug Tracking
:> ------------
:> There should be some way to track tasks and needs for this documentation
:> and
:> any other repos that are moved under this sig. Since it is the currently
:> planned direction for all OpenStack projects (or at least there is a vocal
:> desire for it to be) I think a Storyboard project should be created for
:> this
:> SIG's activities.
:>
:> Plan
:> ----
:> So to recap above, I would propose the following actions be taken:
:>
:> 1. Create sig-operators as a group to manage operator efforts at least
:> related
:> to what needs to be done in repos.
:> 2. Create an openstack/operations-guide repo to be the new home of the
:> operations documentation.
:> 3. Create a new StoryBoard project to help track work in these repos
:> x. Document all this.
:> 9. Profit!
:>
:> I'm willing to work through the steps to get these things set up. Please
:> give
:> feedback if this proposed plan makes sense or if there is anything
:> different
:> that would be preferred.
:>
:> Thanks,
:> Sean
:>
:> On Wed, May 23, 2018 at 06:38:32PM -0700, Chris Morgan wrote:
:> > Hello Everyone,
:> >
:> > In the Ops Community documentation working session today in Vancouver, we
:> > made some really good progress (etherpad here:
:> > https://etherpad.openstack.org/p/YVR-Ops-Community-Docs but not all of
:> the
:> > good stuff is yet written down).
:> >
:> > In short, we're going to course correct on maintaining the Operators
:> Guide,
:> > the HA Guide and Architecture Guide, not edit-in-place via the wiki and
:> > instead try still maintaining them as code, but with a different, new set
:> > of owners, possibly in a new Ops-focused repo. There was a strong
:> consensus
:> > that a) code workflow >> wiki workflow and that b) openstack core docs
:> > tools are just fine.
:> >
:> > There is a lot still to be decided on how where and when, but we do have
:> an
:> > offer of a rewrite of the HA Guide, as long as the changes will be
:> allowed
:> > to actually land, so we expect to actually start showing some progress.
:> >
:> > At the end of the session, people wanted to know how to follow along as
:> > various people work out how to do this... and so for now that place is
:> this
:> > very email thread. The idea is if the code for those documents goes to
:> live
:> > in a different repo, or if new contributors turn up, or if a new version
:> we
:> > will announce/discuss it here until such time as we have a better home
:> for
:> > this initiative.
:> >
:> > Cheers
:> >
:> > Chris
:> >
:> > --
:> > Chris Morgan <mihalis68@gmail.com>
:>
:> > _______________________________________________
:> > OpenStack-operators mailing list
:> > OpenStack-operators@lists.openstack.org
:> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
:>
:>
:> _______________________________________________
:> OpenStack-operators mailing list
:> OpenStack-operators@lists.openstack.org
:> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
:>

:_______________________________________________
:OpenStack-operators mailing list
:OpenStack-operators@lists.openstack.org
:http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators


--

_______________________________________________
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators