> On May 19, 2017, at 9:37 AM, Alexandra Settle <a.set...@outlook.com> wrote: > > > > From: Doug Hellmann <d...@doughellmann.com <mailto:d...@doughellmann.com>> > Date: Friday, May 19, 2017 at 2:33 PM > To: Anne Gentle <annegen...@justwriteclick.com > <mailto:annegen...@justwriteclick.com>> > Cc: Alexandra Settle <a.set...@outlook.com <mailto:a.set...@outlook.com>>, > Openstack-doc-core <openstack-doc-core@lists.launchpad.net > <mailto:openstack-doc-core@lists.launchpad.net>>, Mike Perez > <thin...@gmail.com <mailto:thin...@gmail.com>> > Subject: Re: [Openstack-doc-core] [openstack-doc-core] Summit update > > > On May 18, 2017, at 7:17 PM, Anne Gentle <annegen...@justwriteclick.com > <mailto:annegen...@justwriteclick.com>> wrote: > > > > On Wed, May 17, 2017 at 5:42 AM, Alexandra Settle <a.set...@outlook.com > <mailto:a.set...@outlook.com>> 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 > <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.
Yeah, that seems like it would be a challenge. Maybe a few of the potential new maintainers can do the migration. That would give them a chance to decide how to organize the content, and work out some of the issues with editing something so large in the wiki. > > 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 > <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 > <https://launchpad.net/~openstack-doc-core> > Post to : openstack-doc-core@lists.launchpad.net > <mailto:openstack-doc-core@lists.launchpad.net> > Unsubscribe : https://launchpad.net/~openstack-doc-core > <https://launchpad.net/~openstack-doc-core> > More help : https://help.launchpad.net/ListHelp > <https://help.launchpad.net/ListHelp> > > > > -- > > Read my blog: justwrite.click <https://justwriteclick.com/> > Subscribe to Docs|Code: docslikecode.com <http://docslikecode.com/> > >
-- Mailing list: https://launchpad.net/~openstack-doc-core Post to : openstack-doc-core@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack-doc-core More help : https://help.launchpad.net/ListHelp
