openstack-doc-core team mailing list archive

[Doug Hellmann <doug@xxxxxxxxxxxxxxxx>]

> On May 17, 2017, at 11:52 AM, Andreas Jaeger <aj@xxxxxxxx> wrote:
> 
> 
> On 2017-05-17 12:42, Alexandra Settle 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.
> 
> 
> Thanks Alex for getting all this together! This is really impressive!

Indeed, I know this has been a tough situation to work through. Thank you for taking the lead on finding a resolution.

>> 
>> 
>> 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:
> 
>> [...]
>> 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.
>> 
> 
> We can do that - but importing it in the wiki might be complicated. And
> you miss the option to print it. This would be IMHO "throwing it over
> the fence". If that's how they want to do it, ok, let's do it...
> 
> 
>> [...]
>> 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).
> 
> Including Contributor guide and openstackdocstheme?

The contributor guide is one I hadn’t thought of. Would it make sense to combine the doc contributor guide with the project team guide? We have some sections in that other guide focused on other teams, like release and stable, and if the docs are going to live in various places it may make sense to consolidate the contribution guidelines. Just a thought.

> 
>> 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.
> 
> I'm not seeing better solutions right now ;(
> 
> Thanks,
> Andreas
> -- 
> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
>  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
>       HRB 21284 (AG Nürnberg)
>    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126