[openstack-dev] [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-dev/attachments/20170602/c432e605/attachment.html>
More information about the OpenStack-dev
mailing list