Re: [Openstack-operators] [dev] [doc] Operations Guide future

[Alexandra Settle]

Hey Blair,

Thanks ( I appreciate your offer of assistance. We are in full swing at the 
moment. The spec is very close to being merged. You can view that here: 
https://review.openstack.org/#/c/472275/ 

I am still looking for someone who can help us out with the pandoc conversion. 
I am happy to go through it with said individual.

Cheers,

Alex

On 6/23/17, 3:47 AM, "Blair Bethwaite"  wrote:

Hi Alex,

On 2 June 2017 at 23:13, Alexandra Settle  wrote:
> O I like your thinking – I’m a pandoc fan, so, I’d be interested in
> moving this along using any tools to make it easier.

I can't realistically offer much time on this but I would be happy to
help (ad-hoc) review/catalog/clean-up issues with export.

> I think my only proviso (now I’m thinking about it more) is that we still
> have a link on docs.o.o, but it goes to the wiki page for the Ops Guide.

Agreed, need to maintain discoverability.

-- 
Cheers,
~Blairo


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

Re: [Openstack-operators] [dev] [doc] Operations Guide future

[Blair Bethwaite]

Hi Alex,

On 2 June 2017 at 23:13, Alexandra Settle  wrote:
> O I like your thinking – I’m a pandoc fan, so, I’d be interested in
> moving this along using any tools to make it easier.

I can't realistically offer much time on this but I would be happy to
help (ad-hoc) review/catalog/clean-up issues with export.

> I think my only proviso (now I’m thinking about it more) is that we still
> have a link on docs.o.o, but it goes to the wiki page for the Ops Guide.

Agreed, need to maintain discoverability.

-- 
Cheers,
~Blairo

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

Re: [Openstack-operators] [dev] [doc] Operations Guide future

[Alexandra Settle]

Blair – correct, it was the majority in the room. I just wanted to reach out 
and ensure that operators had a chance to voice opinions and see where we were 
going (

Sounds like option 3 is still the favorable direction. This is going to be a 
really big exercise, lifting the content out of the repos. Are people able to 
help?

Thanks everyone for getting on board (

On 6/2/17, 2:44 AM, "Blair Bethwaite"  wrote:

Hi Alex,

Likewise for option 3. If I recall correctly from the summit session
that was also the main preference in the room?

On 2 June 2017 at 11:15, George Mihaiescu  wrote:
> +1 for option 3
>
>
>
> On Jun 1, 2017, at 11:06, Alexandra Settle  wrote:
>
> Hi everyone,
>
>
>
> I haven’t had any feedback regarding moving the Operations Guide to the
> OpenStack wiki. I’m not taking silence as compliance. I would really like 
to
> hear people’s opinions on this matter.
>
>
>
> To recap:
>
>
>
> Option one: Kill the Operations Guide completely and move the 
Administration
> Guide to project repos.
> Option two: Combine the Operations and Administration Guides (and then 
this
> will be moved into the project-specific repos)
> Option three: Move Operations Guide to OpenStack wiki (for ease of
> operator-specific maintainability) and move the Administration Guide to
> project repos.
>
>
>
> Personally, I think that option 3 is more realistic. The idea for the last
> option is that operators are maintaining operator-specific documentation 
and
> updating it as they go along and we’re not losing anything by combining or
> deleting. I don’t want to lose what we have by going with option 1, and I
> think option 2 is just a workaround without fixing the problem – we are 
not
> getting contributions to the project.
>
>
>
> Thoughts?
>
>
>
> Alex
>
>
>
> From: Alexandra Settle 
> Date: Friday, May 19, 2017 at 1:38 PM
> To: Melvin Hillsman , OpenStack Operators
> 
> Subject: Re: [Openstack-operators] Fwd: [openstack-dev] [openstack-doc]
> [dev] What's up doc? Summit recap edition
>
>
>
> Hi everyone,
>
>
>
> Adding to this, I would like to draw your attention to the last dot point 
of
> my email:
>
>
>
> “One of the key takeaways from the summit was the session that I joint
> moderated with Melvin Hillsman regarding the Operations and Administration
> Guides. You can find the etherpad with notes here:
> https://etherpad.openstack.org/p/admin-ops-guides  The session was really
> helpful – we were able to discuss with the operators present the current
> situation of the documentation team, and how they could help us maintain 
the
> two guides, aimed at the same audience. The operator’s present at the
> session agreed that the Administration Guide was important, and could be
> maintained upstream. However, they voted and agreed that the best course 
of
> action for the Operations Guide was for it to be pulled down and put into 
a
> wiki that the operators could manage themselves. We will be looking at
> actioning this item as soon as possible.”
>
>
>
> I would like to go ahead with this, but I would appreciate feedback from
> operators who were not able to attend the summit. In the etherpad you will
> see the three options that the operators in the room recommended as being
> viable, and the voted option being moving the Operations Guide out of
> docs.openstack.org into a wiki. The aim of this was to empower the
> operations community to take more control of the updates in an environment
> they are more familiar with (and available to others).
>
>
>
> What does everyone think of the proposed options? Questions? Other 
thoughts?
>
>
>
> Alex
>
>
>
> From: Melvin Hillsman 
> Date: Friday, May 19, 2017 at 1:30 PM
> To: OpenStack Operators 
> Subject: [Openstack-operators] Fwd: [openstack-dev] [openstack-doc] [dev]
> What's up doc? Summit recap edition
>
>
>
>
>
> -- Forwarded message --
> From: Alexandra Settle 
> Date: Fri, May 19, 2017 at 6:12 AM
> Subject: [openstack-dev] [openstack-doc] [dev] What's up doc? Summit recap
> edition
> To: "openstack-d...@lists.openstack.org"
> 
> Cc: "OpenStack Development Mailing List (not for usage questions)"
> 
>
>
> Hi everyone,
>
>
> The OpenStack 

Re: [Openstack-operators] [dev] [doc] Operations Guide future

[Blair Bethwaite]

Hi Alex,

Likewise for option 3. If I recall correctly from the summit session
that was also the main preference in the room?

On 2 June 2017 at 11:15, George Mihaiescu  wrote:
> +1 for option 3
>
>
>
> On Jun 1, 2017, at 11:06, Alexandra Settle  wrote:
>
> Hi everyone,
>
>
>
> I haven’t had any feedback regarding moving the Operations Guide to the
> OpenStack wiki. I’m not taking silence as compliance. I would really like to
> hear people’s opinions on this matter.
>
>
>
> To recap:
>
>
>
> Option one: Kill the Operations Guide completely and move the Administration
> Guide to project repos.
> Option two: Combine the Operations and Administration Guides (and then this
> will be moved into the project-specific repos)
> Option three: Move Operations Guide to OpenStack wiki (for ease of
> operator-specific maintainability) and move the Administration Guide to
> project repos.
>
>
>
> Personally, I think that option 3 is more realistic. The idea for the last
> option is that operators are maintaining operator-specific documentation and
> updating it as they go along and we’re not losing anything by combining or
> deleting. I don’t want to lose what we have by going with option 1, and I
> think option 2 is just a workaround without fixing the problem – we are not
> getting contributions to the project.
>
>
>
> Thoughts?
>
>
>
> Alex
>
>
>
> From: Alexandra Settle 
> Date: Friday, May 19, 2017 at 1:38 PM
> To: Melvin Hillsman , OpenStack Operators
> 
> Subject: Re: [Openstack-operators] Fwd: [openstack-dev] [openstack-doc]
> [dev] What's up doc? Summit recap edition
>
>
>
> Hi everyone,
>
>
>
> Adding to this, I would like to draw your attention to the last dot point of
> my email:
>
>
>
> “One of the key takeaways from the summit was the session that I joint
> moderated with Melvin Hillsman regarding the Operations and Administration
> Guides. You can find the etherpad with notes here:
> https://etherpad.openstack.org/p/admin-ops-guides  The session was really
> helpful – we were able to discuss with the operators present the current
> situation of the documentation team, and how they could help us maintain the
> two guides, aimed at the same audience. The operator’s present at the
> session agreed that the Administration Guide was important, and could be
> maintained upstream. However, they voted and agreed that the best course of
> action for the Operations Guide was for it to be pulled down and put into a
> wiki that the operators could manage themselves. We will be looking at
> actioning this item as soon as possible.”
>
>
>
> I would like to go ahead with this, but I would appreciate feedback from
> operators who were not able to attend the summit. In the etherpad you will
> see the three options that the operators in the room recommended as being
> viable, and the voted option being moving the Operations Guide out of
> docs.openstack.org into a wiki. The aim of this was to empower the
> operations community to take more control of the updates in an environment
> they are more familiar with (and available to others).
>
>
>
> What does everyone think of the proposed options? Questions? Other thoughts?
>
>
>
> Alex
>
>
>
> From: Melvin Hillsman 
> Date: Friday, May 19, 2017 at 1:30 PM
> To: OpenStack Operators 
> Subject: [Openstack-operators] Fwd: [openstack-dev] [openstack-doc] [dev]
> What's up doc? Summit recap edition
>
>
>
>
>
> -- Forwarded message --
> From: Alexandra Settle 
> Date: Fri, May 19, 2017 at 6:12 AM
> Subject: [openstack-dev] [openstack-doc] [dev] What's up doc? Summit recap
> edition
> To: "openstack-d...@lists.openstack.org"
> 
> Cc: "OpenStack Development Mailing List (not for usage questions)"
> 
>
>
> Hi everyone,
>
>
> The OpenStack manuals project had a really productive week at the OpenStack
> summit in Boston. You can find a list of all the etherpads and attendees
> here: https://etherpad.openstack.org/p/docs-summit
>
>
>
> As we all know, we are rapidly losing key contributors and core reviewers.
> We are not alone, this is happening across the board. It is making things
> harder, but not impossible. Since our inception in 2010, we’ve been climbing
> higher and higher trying to achieve the best documentation we could, and
> uphold our high standards. This is something to be incredibly proud of.
> However, we now need to take a step back and realise that the amount of work
> we are attempting to maintain is now out of reach for the team size that we
> have. At the moment we have 13 cores, of which none are full time
> contributors or reviewers. This includes myself.
>
>
>
> That being said! I have spent the last week at the summit talking to some of
> our leaders, including Doug 

Re: [Openstack-operators] [dev] [doc] Operations Guide future

[Doug Thompson]

Hi Alexandra,   I have always been in favour of having operations guides 
separate from an administration guide although there needs to be a lot of cross 
reference.
   IMHO, operations guides should have commands and instructions on how to 
diagnose and remedy issues of a running installation.  Administration guides 
should have lots of detail on configuration and how to implement features.
On Thu, 2017-06-01 at 15:06 +, Alexandra Settle wrote:
> Hi everyone,
>  
> I haven’t had any feedback regarding moving the Operations Guide to the 
> OpenStack wiki. I’m not taking silence as compliance. I would really like to 
> hear people’s opinions
>  on this matter.
>  
> To recap:
>  
> 
> Option one: Kill the Operations Guide
>  completely and move the Administration Guide to project repos.Option two: 
> Combine the Operations and
>  Administration Guides (and then this will be moved into the project-specific 
> repos)Option three: Move Operations Guide to
>  OpenStack wiki (for ease of operator-specific maintainability) and move the 
> Administration Guide to project repos.
>  
> Personally, I think that option 3 is more realistic. The idea for the last 
> option is that operators are maintaining operator-specific documentation and 
> updating it as they
>  go along and we’re not losing anything by combining or deleting. I don’t 
> want to lose what we have by going with option 1, and I think option 2 is 
> just a workaround without fixing the problem – we are not getting 
> contributions to the project.
>  
> Thoughts?
>  
> Alex
>  
> 
> From:
> Alexandra Settle 
> 
> Date: Friday, May 19, 2017 at 1:38 PM
> 
> To: Melvin Hillsman , OpenStack Operators 
> 
> 
> Subject: Re: [Openstack-operators] Fwd: [openstack-dev] [openstack-doc] [dev] 
> What's up doc? Summit recap edition
> 
> 
>  
> 
> Hi everyone,
>  
> Adding to this, I would like to draw your attention to the last dot point of 
> my email:
>  
> “One of the key takeaways from the summit was the session that I joint 
> moderated with Melvin Hillsman regarding the Operations and Administration
>  Guides. You can find the etherpad with notes here: 
> https://etherpad.openstack.org/p/admin-ops-guides  The session was really 
> helpful – we were able to discuss with the operators present the current 
> situation of the documentation team, and how they could help us maintain the 
> two guides, aimed at the same
>  audience. The operator’s present at the session agreed that the 
> Administration Guide was important, and could be maintained upstream. 
> However, they voted and agreed that the best course of action for the 
> Operations Guide was for it to be pulled down and put
>  into a wiki that the operators could manage themselves. We will be looking 
> at actioning this item as soon as possible.”
>  
> I would like to go ahead with this, but I would appreciate feedback from 
> operators who were not able to attend the summit. In the etherpad you will
>  see the three options that the operators in the room recommended as being 
> viable, and the voted option being moving the Operations Guide out of 
> docs.openstack.org into a wiki. The aim of this was to empower the operations 
> community to take more control of
>  the updates in an environment they are more familiar with (and available to 
> others).
>  
> What does everyone think of the proposed options? Questions? Other thoughts?
>  
> Alex
>  
> 
> From:
> Melvin Hillsman 
> 
> Date: Friday, May 19, 2017 at 1:30 PM
> 
> To: OpenStack Operators 
> 
> Subject: [Openstack-operators] Fwd: [openstack-dev] [openstack-doc] [dev] 
> What's up doc? Summit recap edition
> 
> 
>  
> 
> 
>  
> 
> 
> -- Forwarded message --
> 
> From: Alexandra Settle 
> 
> Date: Fri, May 19, 2017 at 6:12 AM
> 
> Subject: [openstack-dev] [openstack-doc] [dev] What's up doc? Summit recap 
> edition
> 
> To: "openstack-d...@lists.openstack.org" 
> 
> Cc: "OpenStack Development Mailing List (not for usage questions)" 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> Hi everyone,
> 
> 
> 
> The OpenStack manuals project had a really productive week at the OpenStack 
> summit in Boston. You can find a list of all the etherpads and attendees here:
> https://etherpad.openstack.org/p/docs-summit
> 
> 
>  
> 
> As we all know, we are rapidly losing key contributors and core reviewers. We 
> are not alone, this is happening across the board. It is making things 
> harder, but not impossible. Since our inception in 2010, we’ve been climbing
>  higher and higher trying to achieve the best documentation we could, and 
> uphold our high standards. This is something to be incredibly proud of. 
> However, we now need to take a step back and realise that the amount of work 
> we are attempting to maintain