Jump to: navigation, search

Documentation/WhatsUpDoc

Documentation Newsletters

This is where I draft the 'What's Up, Doc?' documentation newsletters. The newsletter is distributed every Friday (ish), to the openstack-docs mailing list. If you want to be added to the distribution list, or have content to add, please edit these sections:

Distribution List

  • OpenStack Docs Mailing List <Openstack-docs@lists.openstack.org>
  • OpenStack Development Mailing List <openstack-dev@lists.openstack.org>

Your suggestions for content

  • Add
  • Your
  • Content
  • Here

12 June 2015

Hi everyone,

If you have content you would like to add, or you would like to be added to the distribution list, please email me directly at openstack@lanabrindley.com. If you want to see my early drafts and typos, or check on old newsletters, you can do so here: https://wiki.openstack.org/w/index.php?title=Documentation/WhatsUpDoc

Progress towards Liberty

  • RST conversion:
  • User Guides information architecture overhaul
    • Waiting on the RST conversion of the Cloud Admin Guide to be complete
  • Greater focus on helping out devs with docs in their repo
    • No progress this week
  • Improve how we communicate with and support our corporate contributors
    • I met with Alison of Oracle to discuss how we can help out their team
  • Improve communication with Cross Team Liaisons

Kilo Branching

Thanks to Andreas, Anne, and Tom for getting the Stable/Kilo branch completed this week. With this, Kilo is now complete* and patches for the Install Guide and the Config Reference will now be against Liberty unless you specifically backport a change to Kilo. You can do this by committing to master with the line Backport: Kilo in your commit message. Remember that all other book are continuously integrated, and this isn't necessary.

[*] Anne: feel free to go have a lie down ;)

RST Migration

The next books we are focusing on for RST conversion are the Install Guide, Cloud Admin Guide, and the HA Guide. If you would like to assist, please get in touch with the appropriate speciality team.


For books that are now being converted, don't forget that any change you make to the XML must also be made to the RST version until conversion is complete. Our lovely team of cores will be keeping an eye out to make sure loose changes to XML don't pass the gate, but try to help them out by pointing out both patches in your reviews.

New Core Reviewer Process

We did our first monthly round of Core Team review this week, and would like to welcome our newest core team member, Darren Chan. We also bid a fond farewell to Summer Long and Bryan Payne, who have been great core team members and contributors, but have now moved on to other adventures. We sincerely thank them both for their commitment over the time they were core.

The new core process is documented here: https://wiki.openstack.org/wiki/Documentation/HowTo#Achieving_core_reviewer_status The next round will be around 1 July.

RST Common Files

We're coming across some build issues in the RST books with common files. If you have a common file in the ToC of a guide, please move it into the source file of that guide to prevent build issues. Using :orphan: directive marking on the file can also prevent sphinx marking the doc as an error.

Doc team meeting

The APAC meeting was held this week, see the minutes here to catch up: https://wiki.openstack.org/wiki/Documentation/MeetingLogs#2015-06-10

Next meetings are: US: Wednesday 17 June, 14:00:00 UTC APAC: Wednesday 24 June, 00:30:00 UTC

Please go ahead and add any agenda items to the meeting page here: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting#Agenda_for_next_meeting

Thanks! Lana

5 June 2015

Hi everyone,

With our Kilo branch now cut, we're running headlong into the Liberty development cycle! And don't forget to have your say on what the M release should be called: https://wiki.openstack.org/wiki/Release_Naming/M_Proposals

If you have content you would like to add, or you would like to be added to the distribution list, please email me directly at openstack@lanabrindley.com. I've also decided to start drafting these 'in the open' (as it were). If you want to see my early drafts and typos, or check on old newsletters, you can do so here: https://wiki.openstack.org/w/index.php?title=Documentation/WhatsUpDoc

Progress towards Liberty

  • RST conversion:
  • User Guides information architecture overhaul
    • Waiting on the RST conversion of the Cloud Admin Guide to be complete
  • Greater focus on helping out devs with docs in their repo
    • No progress this week
  • Improve how we communicate with and support our corporate contributors
    • I met with Alison of Oracle to discuss how we can help out their team
  • Improve communication with Cross Team Liaisons

Kilo Branching

Thanks to Andreas, Anne, and Tom for getting the Stable/Kilo branch completed this week. With this, Kilo is now complete* and patches for the Install Guide and the Config Reference will now be against Liberty unless you specifically backport a change to Kilo. You can do this by committing to master with the line Backport: Kilo in your commit message. Remember that all other book are continuously integrated, and this isn't necessary.

[*] Anne: feel free to go have a lie down ;)

RST Migration

The next books we are focusing on for RST conversion are the Install Guide, Cloud Admin Guide, and the HA Guide. If you would like to assist, please get in touch with the appropriate speciality team.


For books that are now being converted, don't forget that any change you make to the XML must also be made to the RST version until conversion is complete. Our lovely team of cores will be keeping an eye out to make sure loose changes to XML don't pass the gate, but try to help them out by pointing out both patches in your reviews.

New Core Reviewer Process

We did our first monthly round of Core Team review this week, and would like to welcome our newest core team member, Darren Chan. We also bid a fond farewell to Summer Long and Bryan Payne, who have been great core team members and contributors, but have now moved on to other adventures. We sincerely thank them both for their commitment over the time they were core.

The new core process is documented here: https://wiki.openstack.org/wiki/Documentation/HowTo#Achieving_core_reviewer_status The next round will be around 1 July.

Doc team meeting

The US meeting was held this week, see the minutes here to catch up: https://wiki.openstack.org/wiki/Documentation/MeetingLogs#2015-06-03

Thanks Shilla for running the US team meeting!

Next meetings are: APAC: Wednesday 10 June, 00:30:00 UTC US: Wednesday 17 June, 14:00:00 UTC

Please go ahead and add any agenda items to the meeting page here: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting#Agenda_for_next_meeting

Thanks! Lana


29 May 2015

Hi everyone,

Continuing in Anne's fine tradition, I intend to send these out every Friday. If you have content you would like to add, or you would like to be added to the distribution list, please email me directly at openstack@lanabrindley.com. I've also decided to start drafting these 'in the open' (as it were). If you want to see my early drafts and typos, or check on old newsletters, you can do so here: https://wiki.openstack.org/w/index.php?title=Documentation/WhatsUpDoc

Design Summit

The Design Summit was a great success. We had ten sessions for docs overall, including two workgroups and a contributors' meetup. Thanks to everyone who came along (or participated remotely!) and had their say on the Liberty release. I've been spending time gathering my thoughts after the Summit, and have summarised the etherpad notes on the wiki here: https://wiki.openstack.org/w/index.php?title=Documentation/Liberty You can also see the original etherpads here: https://wiki.openstack.org/wiki/Design_Summit/Liberty/Etherpads#Documentation

In short, the main things I would like us to achieve for Liberty are:

  • RST conversion: Install Guide, Cloud Admin Guide, HA Guide
  • User Guides information architecture overhaul.
  • Greater focus on helping out devs with docs in their repo
  • Improve how we communicate with and support our corporate contributors


If you have a burning issue that didn't get addressed during the Summit, or that you think I've forgotten, now would be your chance to tell me about it! Look out for Blueprints and Specs for this work over the next couple of weeks.

RST Migration

The next books we are focusing on for RST conversion are the Install Guide, Cloud Admin Guide, and the HA Guide. If you would like to assist, please get in touch with the appropriate speciality team.


New Core Reviewer Process

One of the simpler changes I was asked to implement at the Design Summit was a new core reviewer process, with the aim of making it a more balanced approach to selecting core team members. We decided on a process that combines a monthly statistics-based selection process with a continuous nomination-based process. I've written up the details on the HowTo here: https://wiki.openstack.org/wiki/Documentation/HowTo#Achieving_core_reviewer_status and will implement the first round on 1 June.

Doc team meeting

APAC meeting was held this week, see the minutes here to catch up: https://wiki.openstack.org/wiki/Documentation/MeetingLogs#2015-05-27

Thanks to Joe for holding the APAC fort while I was travelling!

Next meetings are: US: Wednesday 3 June, 14:00:00 UTC APAC: Wednesday 10 June, 00:30:00 UTC

Please go ahead and add any agenda items to the meeting page here: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting#Agenda_for_next_meeting

Thanks! Lana

Retrieved from "https://wiki.openstack.org/w/index.php?title=Documentation/WhatsUpDoc&oldid=83259"