openstack-doc-core team mailing list archive

[Alexandra Settle <a.settle@xxxxxxxxxxx>]

From: Doug Hellmann <doug@xxxxxxxxxxxxxxxx>
Date: Friday, May 19, 2017 at 2:33 PM
To: Anne Gentle <annegentle@xxxxxxxxxxxxxxxxxx>
Cc: Alexandra Settle <a.settle@xxxxxxxxxxx>, Openstack-doc-core <openstack-doc-core@xxxxxxxxxxxxxxxxxxx>, Mike Perez <thingee@xxxxxxxxx>
Subject: Re: [Openstack-doc-core] [openstack-doc-core] Summit update


On May 18, 2017, at 7:17 PM, Anne Gentle <annegentle@xxxxxxxxxxxxxxxxxx<mailto:annegentle@xxxxxxxxxxxxxxxxxx>> wrote:



On Wed, May 17, 2017 at 5:42 AM, Alexandra Settle <a.settle@xxxxxxxxxxx<mailto:a.settle@xxxxxxxxxxx>> wrote:
Hi everyone,

Before I send out my summary email to the greater mailing lists, I felt I should reach out to you all first as the gate keepers of the documentation project.

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

Here’s a few action items I’d like to highlight:

1.       We have a detailed outline in the above etherpad<https://etherpad.openstack.org/p/doc-planning> on the action items going forward with the Installation Guide.
a.       Send email to the openstack-dev mailing list requesting input with regards to the project-specific installation guide move:
                                                                i.      Request solutions from the remaining teams that are pushing back against in-tree content.
                                                               ii.      Agree upon long-term maintenance solution for Installation Guide.
2.       In the Administration and Operations Guide session<https://etherpad.openstack.org/p/admin-ops-guides> we asked operators what they wanted and how they wanted to go forward. Through a vote in the room, operators agreed that they would like to see the Operations Guide moved out of the openstack-manuals repo, and placed into the OpenStack wiki<http://wiki.openstack.org/> for their own maintenance. We lose ownership, but we also empower the operators to maintain their own guide.

Sounds fine, though who will do the migration? I'd also make sure it's not only the people in the room who traveled that get a vote.

What’s driving the request to use the wiki, instead of continuing to maintain the guide in gerrit?

Historically, we have tried time and time again to get operators to commit and help maintain the guide in gerrit. This doesn’t work, they don’t want to use/setup git and gerrit. So, since we’ve essentially been maintaining two operators guides (Admin and Ops), I was interested to know who used them, and why, and how.
When I asked the room what they preferred using, a lot of the answers were things like Confluence, Google Docs, etc. To keep this open source, and in the OpenStack community, I suggested the OpenStack wiki.

The session revealed that operators were mainly using the Admin Guide, but used the Ops Guide when learning. They would be happy to look after the guide in an unofficial capacity, and at the time believed it would be more likely updated if the operators had the power to do so without having to setup the contribution system.

Admittedly, they were concerned that there would be no version control.

3.       Work on improving the config ref auto-generation files using sphinx extensions:
a.       Move away from using the flagmapping files (reduce manual labour)
b.       See: https://etherpad.openstack.org/p/config-ref-spec
Yay.
4.       Ensure the CLI ref is documenting the unified client (move to the OSC repo).
Does this mean stop creating the nova CLI ref and so on? Sounds good to me.
5.       Implement the archiving solution for the Pike release.

Do we have someone assigned now?

6.       After the Pike release, include a note on the Architecture Guide and cease edits after that point in time.
Can this also go to the wiki or no? Not sure why this one stays for Pike?
7.       After a period of time, any documents that are not being maintained, or groups have not taken ownership (Examples: Security, HA, and Networking Guides), they will be moved out of the openstack-manuals repo and onto the Legacy list.

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).


Sounds like the natural next step.

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



--
Mailing list: https://launchpad.net/~openstack-doc-core
Post to     : openstack-doc-core@xxxxxxxxxxxxxxxxxxx<mailto:openstack-doc-core@xxxxxxxxxxxxxxxxxxx>
Unsubscribe : https://launchpad.net/~openstack-doc-core
More help   : https://help.launchpad.net/ListHelp



--

Read my blog: justwrite.click<https://justwriteclick.com/>
Subscribe to Docs|Code: docslikecode.com<http://docslikecode.com/>