settingsLogin | Registersettings

[Openstack-operators] [doc] Operations Guide removal

0 votes

Hi operators,
Please be aware that I have proposed the following patch: https://review.openstack.org/#/c/483937/

This removes the Operations Guide from the openstack-manuals repo and will no longer be accessible via docs.openstack.org after the patch merges.
The documentation team does not have the resources to move the ops guide to the wiki ourselves. If you are able to work on the migration, please check out the ‘before-migration’ tag in the repo to access the deleted content. [0]
Once the ops guide is migrated to the wiki, we will help you add a redirect so that the old link on docs.openstack.org will allow users to find the content in the new location.
Thanks,
Alex

[0] https://github.com/openstack/openstack-manuals/tree/before-migration


OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
asked Aug 12, 2017 in openstack-operators by a.settle_at_outlook. (3,220 points)   2 2

20 Responses

0 votes

On 14/07/17 23:48, Alexandra Settle wrote:
Please be aware that I have proposed the following patch: https://review.openstack.org/#/c/483937/

This removes the Operations Guide from the openstack-manuals repo and will no longer be accessible via docs.openstack.org after the patch merges.

I am unclear on the order of events here. Recently we found some documentation[1] had been removed because it was going to be put up somewhere else, but was not yet available. Is this the case here? Could it instead be put up somewhere else shortly before removing it from the repo?

Regards,
Greg.

[1] I do not recall which, but I can find out if desired


OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
responded Jul 17, 2017 by Gregory_Orange (460 points)   1 1
0 votes

On 2017-07-17 04:39, Gregory Orange wrote:
On 14/07/17 23:48, Alexandra Settle wrote:

Please be aware that I have proposed the following patch:
https://review.openstack.org/#/c/483937/

This removes the Operations Guide from the openstack-manuals repo and
will no longer be accessible via docs.openstack.org after the patch
merges.

I am unclear on the order of events here. Recently we found some
documentation[1] had been removed because it was going to be put up
somewhere else, but was not yet available. Is this the case here? Could
it instead be put up somewhere else shortly before removing it from
the repo?

The repo was tagged, so that you can always get it - tag is
before-migration,

Andreas
--
Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Felix Imendörffer, Jane Smithard, Graham Norton,
HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126


OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
responded Jul 17, 2017 by Andreas_Jaeger (17,140 points)   2 3 4
0 votes

Hi Greg,

We have been working to fulfil the implementation process that is outlined in the migration spec[0]

I have been emailing the ops list calling for volunteers to help migrate the operations guide over to the OpenStack wiki. I have had a volunteer, but he is currently on vacation. Perhaps this is to what you are referring to?

As Andreas noted, any documentation can always be accessed using the before-migration tag in the openstack-manuals repo.[1]

If perhaps you are referring to another document, it would be helpful if you could find the relevant materials :)

Hopefully this helps,

Alex

[0] http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html
[1] https://github.com/openstack/openstack-manuals/tree/before-migration

On 7/17/17, 3:39 AM, "Gregory Orange" gregory.orange@pawsey.org.au wrote:

On 14/07/17 23:48, Alexandra Settle wrote:

Please be aware that I have proposed the following patch: https://review.openstack.org/#/c/483937/

This removes the Operations Guide from the openstack-manuals repo and will no longer be accessible via docs.openstack.org after the patch merges.

I am unclear on the order of events here. Recently we found some documentation[1] had been removed because it was going to be put up somewhere else, but was not yet available. Is this the case here? Could it instead be put up somewhere else shortly *before* removing it from the repo?

Regards,
Greg.

[1] I do not recall which, but I can find out if desired

_______________________________________________
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
responded Jul 17, 2017 by a.settle_at_outlook. (3,220 points)   2 2
0 votes

Hello Alex and Andreas,

On 17/07/17 16:50, Alexandra Settle wrote:
I have been emailing the ops list calling for volunteers to help migrate the operations guide over to the OpenStack wiki. I have had a volunteer, but he is currently on vacation. Perhaps this is to what you are referring to?

As Andreas noted, any documentation can always be accessed using the before-migration tag in the openstack-manuals repo.

Thank you both for your responses. The way I read this is: The documentation will become unavailable in its current form, accessible only via github.com; the links within those pages to docs.openstack.org will break, and the navigation layout will be absent. While I appreciate that the material will technically still be available, it will be markedly less accessible to someone trawling for information who does not already have a strong knowledge of that documentation.

Greg.


OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
responded Jul 18, 2017 by Gregory_Orange (460 points)   1 1
0 votes

On 2017-07-18 03:20, Gregory Orange wrote:
Hello Alex and Andreas,

On 17/07/17 16:50, Alexandra Settle wrote:

I have been emailing the ops list calling for volunteers to help
migrate the operations guide over to the OpenStack wiki. I have had a
volunteer, but he is currently on vacation. Perhaps this is to what
you are referring to?

As Andreas noted, any documentation can always be accessed using the
before-migration tag in the openstack-manuals repo.

Thank you both for your responses. The way I read this is: The
documentation will become unavailable in its current form, accessible
only via github.com; the links within those pages to docs.openstack.org
will break, and the navigation layout will be absent. While I appreciate
that the material will technically still be available, it will be
markedly less accessible to someone trawling for information who does
not already have a strong knowledge of that documentation.

Gregory, we discussed this in the past here. The guide is outdated and
orphaned. We asked how to move forward and the feedback by operators
was: We (= some operators) move it to the wiki and maintain it there.

Yes, we're not going to keep an outdated version published as is. This
needs people to drive the guide forward and none have shown up to move
it forward in the existing form,

Andreas
--
Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Felix Imendörffer, Jane Smithard, Graham Norton,
HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126


OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
responded Jul 18, 2017 by Andreas_Jaeger (17,140 points)   2 3 4
0 votes

On 18/07/17 14:18, Andreas Jaeger wrote:
Gregory, we discussed this in the past here. The guide is outdated and
orphaned. We asked how to move forward and the feedback by operators
was: We (= some operators) move it to the wiki and maintain it there.

Yes, we're not going to keep an outdated version published as is. This
needs people to drive the guide forward and none have shown up to move
it forward in the existing form,

Please forgive my naivete here - I am quite new to OpenStack and as such to the community. I have found that in this project as well as in others, old documentation can be surprisingly useful, especially when marked with a date or version.

I recognise that volunteer time is limited, and am interested to see how the new ideas for documentation will go. At the same time, significantly reduced access to documentation - yes, even outdated, orphaned documentation - will make life more difficult for this new operator. If the decision is fixed and there is no will to avoid an outage in this manner, then I guess that is about all I can say.

I will say a word of thanks to you and all of the contributors to the documentation so far. It is critical to anyone starting to use such a massive set of software. I hope that the migration to wiki arrangements is smooth and successful.

Regards,
Greg.


OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
responded Jul 18, 2017 by Gregory_Orange (460 points)   1 1
0 votes
Please forgive my naivete here - I am quite new to OpenStack and as such to the community. I have found that in this project as well as in others, old documentation

.. can be surprisingly useful, especially when marked with a date or version.

We completely agree with you here, which is why we are attempting to give this document back to the operations community. This does, however, mean a small amount of downtime.

I recognise that volunteer time is limited, and am interested to see how the new ideas for documentation will go. At the same time, significantly reduced access to
documentation - yes, even outdated, orphaned documentation - will make life more difficult for this new operator. If the decision is fixed and there is no will to avoid
an outage in this manner, then I guess that is about all I can say.

We also completely agree with you here too. However, one of the many discussions that has continuously come up on ML and during summit and design conference sessions is that our operators find it difficult to contribute to the documentation as is. Our method of treating documentation like code does not suit all, so this is in part an attempt to solve that problem. This does mean that along the way, we are going to have some downtime. But the end goal is to allow our operators to access documentation to be able to update more easily and frequently – hopefully to help future, new, operators like yourself.

The decision has been made, per say. But we hope that this new solution will prove to be fruitful :)

I will say a word of thanks to you and all of the contributors to the documentation so far. It is critical to anyone starting to use such a massive set of software. I hope
that the migration to wiki arrangements is smooth and successful.

So far, so good! Thanks for your note, Greg :) please reach out with any concerns or questions you may have. I’m on IRC as “asettle” or easily contactable via email if that suits you best :)

_______________________________________________
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
responded Jul 18, 2017 by a.settle_at_outlook. (3,220 points)   2 2
0 votes

Hi Alex,

I just managed to take a half hour to look at this and have a few
questions/comments towards making a plan for how to proceed with
moving the Ops Guide content to the wiki...

1) Need to define wiki location and structure. Curiously at the moment
there is already meta content at
https://wiki.openstack.org/wiki/Documentation/OpsGuide, Maybe the
content could live at https://wiki.openstack.org/wiki/OpsGuide? I
think it makes sense to follow the existing structure with possible
exception of culling wrong / very-out-of-date content (but perhaps
anything like that should be done as a later step and keep it simple
aiming for a "like-for-like" migration to start with)...?

2) Getting the content into the wiki. Looks like there is no obvious
up-to-date RST import functionality for MediaWiki. Pandoc seems as
though it might support some useful conversions but I didn't try this
yet and don't have any experience with it - can anyone say with
authority whether it is worth pursuing?

3) Future management - obvious can of worms given this is much better
addressed by all the tooling and scaffolding the docs team already
provides around the repos... but nonetheless some expectations may
need to be set upfront to avoid future pain.

Cheers,

On 15 July 2017 at 01:48, Alexandra Settle a.settle@outlook.com wrote:
Hi operators,

Please be aware that I have proposed the following patch:
https://review.openstack.org/#/c/483937/

This removes the Operations Guide from the openstack-manuals repo and will
no longer be accessible via docs.openstack.org after the patch merges.

The documentation team does not have the resources to move the ops guide to
the wiki ourselves. If you are able to work on the migration, please check
out the ‘before-migration’ tag in the repo to access the deleted content.
[0]

Once the ops guide is migrated to the wiki, we will help you add a redirect
so that the old link on docs.openstack.org will allow users to find the
content in the new location.

Thanks,

Alex

[0] https://github.com/openstack/openstack-manuals/tree/before-migration


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

--
Cheers,
~Blairo


OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
responded Jul 19, 2017 by Blair_Bethwaite (4,080 points)   1 3 5
0 votes

Hey Blair!

Thanks for looking into this… Adding Mario and Erik who both also volunteered their time :)

  1. I can say confidently that the content that lives at https://wiki.openstack.org/wiki/Documentation/OpsGuide can be removed. I am happy to do this if you would like to use this URL?
  2. We (very successfully) used pandoc during our conversion from XML to RST. I would recommend it. I admit I haven’t tried converting to a mediaWiki format. But hey, worth trying… I guess the other option is manually copying across and editing. (Unless someone has a script lying around?)
  3. It’s a good question, one I’m not really sure how to answer. The idea of pushing back to the wiki was so that the operators can own. Having the guide linked from docs.o.o will still ensure there is traffic, and people are able to edit. Perhaps the best idea for this is to use the documentation liaison for Ops as a first point of call? What do you think about that? Currently Robert Starmer is our liaison (https://wiki.openstack.org/wiki/CrossProjectLiaisons#Documentation ) but seeing as we’re now making this more of an official ownership thing, we should be revisiting the responsibilities of the ops docs liaison?

Cheers,

Alex

On 7/19/17, 11:40 AM, "Blair Bethwaite" blair.bethwaite@gmail.com wrote:

Hi Alex,

I just managed to take a half hour to look at this and have a few
questions/comments towards making a plan for how to proceed with
moving the Ops Guide content to the wiki...

1) Need to define wiki location and structure. Curiously at the moment
there is already meta content at
https://wiki.openstack.org/wiki/Documentation/OpsGuide, Maybe the
content could live at https://wiki.openstack.org/wiki/OpsGuide? I
think it makes sense to follow the existing structure with possible
exception of culling wrong / very-out-of-date content (but perhaps
anything like that should be done as a later step and keep it simple
aiming for a "like-for-like" migration to start with)...?

2) Getting the content into the wiki. Looks like there is no obvious
up-to-date RST import functionality for MediaWiki. Pandoc seems as
though it might support some useful conversions but I didn't try this
yet and don't have any experience with it - can anyone say with
authority whether it is worth pursuing?

3) Future management - obvious can of worms given this is much better
addressed by all the tooling and scaffolding the docs team already
provides around the repos... but nonetheless some expectations may
need to be set upfront to avoid future pain.

Cheers,

On 15 July 2017 at 01:48, Alexandra Settle <a.settle@outlook.com> wrote:

Hi operators,

Please be aware that I have proposed the following patch:
https://review.openstack.org/#/c/483937/

This removes the Operations Guide from the openstack-manuals repo and will
no longer be accessible via docs.openstack.org after the patch merges.

The documentation team does not have the resources to move the ops guide to
the wiki ourselves. If you are able to work on the migration, please check
out the ‘before-migration’ tag in the repo to access the deleted content.
[0]

Once the ops guide is migrated to the wiki, we will help you add a redirect
so that the old link on docs.openstack.org will allow users to find the
content in the new location.

Thanks,

Alex

[0] https://github.com/openstack/openstack-manuals/tree/before-migration


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
-- 
Cheers,
~Blairo


OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
responded Jul 19, 2017 by a.settle_at_outlook. (3,220 points)   2 2
0 votes

Excerpts from Blair Bethwaite's message of 2017-07-19 20:40:25 +1000:

Hi Alex,

I just managed to take a half hour to look at this and have a few
questions/comments towards making a plan for how to proceed with
moving the Ops Guide content to the wiki...

1) Need to define wiki location and structure. Curiously at the moment
there is already meta content at
https://wiki.openstack.org/wiki/Documentation/OpsGuide, Maybe the
content could live at https://wiki.openstack.org/wiki/OpsGuide? I
think it makes sense to follow the existing structure with possible
exception of culling wrong / very-out-of-date content (but perhaps
anything like that should be done as a later step and keep it simple
aiming for a "like-for-like" migration to start with)...?

Yes, I would recommend moving the existing content and then making any
major changes to it.

2) Getting the content into the wiki. Looks like there is no obvious
up-to-date RST import functionality for MediaWiki. Pandoc seems as
though it might support some useful conversions but I didn't try this
yet and don't have any experience with it - can anyone say with
authority whether it is worth pursuing?

I can't say with authority myself, but I can refer to Anne as an
authority. :-)

3) Future management - obvious can of worms given this is much better
addressed by all the tooling and scaffolding the docs team already
provides around the repos... but nonetheless some expectations may
need to be set upfront to avoid future pain.

What sort of issues do you foresee?

Doug


OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
responded Jul 19, 2017 by Doug_Hellmann (87,520 points)   3 4 8
...