[openstack-dev] [Openstack-operators] [dev] [doc] Operations Guide future
Alexandra Settle
a.settle at outlook.com
Fri Jun 2 13:13:07 UTC 2017
Ohhhh 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 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.
From: Anne Gentle <annegentle at justwriteclick.com>
Date: Friday, June 2, 2017 at 1:53 PM
To: Alexandra Settle <a.settle at outlook.com>
Cc: Blair Bethwaite <blair.bethwaite at gmail.com>, OpenStack Operators <openstack-operators at lists.openstack.org>, "OpenStack Development Mailing List (not for usage questions)" <openstack-dev at lists.openstack.org>, "openstack-docs at lists.openstack.org" <openstack-docs at lists.openstack.org>
Subject: Re: [Openstack-operators] [dev] [doc] Operations Guide future
I'm okay with option 3.
Since we hadn't heard from anyone yet who can do the work, I thought I'd describe a super small experiment to try. If you're interested in the export, run an experiment with Pandoc to convert from RST to Mediawiki. http://pandoc.org/demos.html
You'll likely still have cleanup but it's a start. Only convert troubleshooting to start, which gets the most hits: docs.openstack.org/<http://docs.openstack.org/>ops-guide/ops-network-troubleshooting.html
Then see how much you get from Pandoc.
Let us know how it goes, I'm curious!
Anne
On Fri, Jun 2, 2017 at 4:03 AM, Alexandra Settle <a.settle at outlook.com<mailto:a.settle at outlook.com>> wrote:
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" <blair.bethwaite at gmail.com<mailto:blair.bethwaite at gmail.com>> 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 <lmihaiescu at gmail.com<mailto:lmihaiescu at gmail.com>> wrote:
> +1 for option 3
>
>
>
> On Jun 1, 2017, at 11:06, Alexandra Settle <a.settle at outlook.com<mailto:a.settle at outlook.com>> 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 <a.settle at outlook.com<mailto:a.settle at outlook.com>>
> Date: Friday, May 19, 2017 at 1:38 PM
> To: Melvin Hillsman <mrhillsman at gmail.com<mailto:mrhillsman at gmail.com>>, OpenStack Operators
> <openstack-operators at lists.openstack.org<mailto:openstack-operators at lists.openstack.org>>
> 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<http://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 <mrhillsman at gmail.com<mailto:mrhillsman at gmail.com>>
> Date: Friday, May 19, 2017 at 1:30 PM
> To: OpenStack Operators <openstack-operators at lists.openstack.org<mailto:openstack-operators at lists.openstack.org>>
> Subject: [Openstack-operators] Fwd: [openstack-dev] [openstack-doc] [dev]
> What's up doc? Summit recap edition
>
>
>
>
>
> ---------- Forwarded message ----------
> From: Alexandra Settle <a.settle at outlook.com<mailto:a.settle at outlook.com>>
> Date: Fri, May 19, 2017 at 6:12 AM
> Subject: [openstack-dev] [openstack-doc] [dev] What's up doc? Summit recap
> edition
> To: "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>"
> <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>>
> Cc: "OpenStack Development Mailing List (not for usage questions)"
> <openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>>
>
>
> 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 Hellmann (cc’d), Jonathan Bryce and Mike Perez
> regarding the future of the project. Between myself and other community
> members, we have been drafting plans and coming up with a new direction that
> will hopefully be sustainable in the long-term.
>
>
>
> I am interested to hear your thoughts. I want to make sure that everyone
> feels that we’re headed in the right direction first and foremost. All of
> these action items are documented in this WIP etherpad:
> https://etherpad.openstack.org/p/doc-planning
>
>
>
> Some further highlights from the event…
>
>
>
> · The documentation team was represented by myself, Olga, and Alex
> Adamov for the Project Update: Documentation on the Monday. If you’d like to
> catch up with what we talked about, the video is available online now:
> https://www.youtube.com/watch?v=jcfbKxbpRvc The translation team PTL, Ian
> Choi, also had a session about getting more involved with the I18N team. You
> can view that video here: https://www.youtube.com/watch?v=ybFI4nez_Z8
>
>
>
> · Ian and I also hosted the joint I18N and documentation onboarding
> session. We were visited by some friendly faces, and some new ones. Between
> Ian and myself, we discussed the documentation and translation workflows,
> and how to get involved (the mailing list, IRC channel, etc). Which was lots
> of fun :) we’d love to see more people there in the future, hopefully we’ll
> slowly get there!
>
>
>
> · This week I was focusing heavily on making the community aware
> that the documentation team was struggling to maintain contributors, but
> continuing with the same amount of work. This was a heavy conversation to be
> having, but it posed some really interesting questions to key leaders, and
> hopefully raised appropriate concerns. Ildiko and I hosted “OpenStack
> documentation: The future depends on all of us”. This was a really
> interesting session. I was able to pose to the group of attendees that the
> documentation team was struggling to maintain contributions. Major Hayden
> was kind enough to take notes during the session, you can find those here:
> https://etherpad.openstack.org/p/doc-future The project teams that came and
> represented their groups were interested in discussing the project-specific
> documentation (is living in the project’s repo tree the best place?) and
> voiced concerns I had otherwise not heard before. I recommend reading the
> notes to get a better idea :)
>
>
>
> · Kendall Nelson and Ildiko also hosted a session on the OpenStack
> Upstream Institute highlights. I recommend watching the video which is now
> live and available here:
> https://www.openstack.org/videos/boston-2017/openstack-upstream-institute-highlights
>
>
>
> · 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.
>
>
>
> These action items will free up the documentation team to become gate
> keepers and reviewers of documentation. Our key focus as a team will be on
> the tooling for the docs.openstack.org<http://docs.openstack.org> site (including the API docs).
>
>
>
> I’m really interested to hear everyone’s thoughts going forward – this is
> not set in stone. We need to change our strategy, and now is the time. If
> you’d rather reach out and discuss this personally, asettle on IRC is always
> the best place to find me.
>
>
>
> Thanks,
>
>
>
> Alex
>
>
>
>
>
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe<http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe>
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
>
>
>
> --
>
> --
>
> Kind regards,
>
> Melvin Hillsman
>
> mrhillsman at gmail.com<mailto:mrhillsman at gmail.com>
> mobile: (832) 264-2646<tel:%28832%29%20264-2646>
>
> Learner | Ideation | Belief | Responsibility | Command
>
> _______________________________________________
> OpenStack-operators mailing list
> OpenStack-operators at lists.openstack.org<mailto:OpenStack-operators at lists.openstack.org>
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>
>
> _______________________________________________
> OpenStack-operators mailing list
> OpenStack-operators at lists.openstack.org<mailto:OpenStack-operators at lists.openstack.org>
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>
--
Cheers,
~Blairo
_______________________________________________
OpenStack-operators mailing list
OpenStack-operators at lists.openstack.org<mailto:OpenStack-operators at lists.openstack.org>
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
--
Read my blog: justwrite.click<https://justwriteclick.com>
Subscribe to Docs|Code: docslikecode.com<http://docslikecode.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20170602/08f9d68b/attachment.html>
More information about the OpenStack-dev
mailing list