openstack-doc-core team mailing list archive

[Anne Gentle <annegentle@xxxxxxxxxxxxxxxxxx>]

On Wed, May 17, 2017 at 5:42 AM, Alexandra Settle <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.


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