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

Anne Gentle annegentle at justwriteclick.com
Fri Jun 2 12:53:04 UTC 2017


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/
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>
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> 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>
> wrote:
>     > +1 for option 3
>     >
>     >
>     >
>     > On Jun 1, 2017, at 11:06, Alexandra Settle <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>
>     > Date: Friday, May 19, 2017 at 1:38 PM
>     > To: Melvin Hillsman <mrhillsman at gmail.com>, OpenStack Operators
>     > <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 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>
>     > Date: Friday, May 19, 2017 at 1:30 PM
>     > To: OpenStack Operators <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>
>     > 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"
>     > <openstack-docs at lists.openstack.org>
>     > Cc: "OpenStack Development Mailing List (not for usage questions)"
>     > <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 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://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>     >
>     >
>     >
>     >
>     >
>     > --
>     >
>     > --
>     >
>     > Kind regards,
>     >
>     > Melvin Hillsman
>     >
>     > mrhillsman at gmail.com
>     > mobile: (832) 264-2646
>     >
>     > Learner | Ideation | Belief | Responsibility | Command
>     >
>     > _______________________________________________
>     > OpenStack-operators mailing list
>     > 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
>     > http://lists.openstack.org/cgi-bin/mailman/listinfo/
> openstack-operators
>     >
>
>
>
>     --
>     Cheers,
>     ~Blairo
>
>
> _______________________________________________
> OpenStack-operators mailing list
> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-operators/attachments/20170602/c432e605/attachment-0001.html>


More information about the OpenStack-operators mailing list