Jump to: navigation, search

Difference between revisions of "Documentation/WhatsUpDoc"

m
 
(380 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
= Documentation Newsletters =
 
= Documentation Newsletters =
 
+
This is where I draft the 'What's Up, Doc?' documentation newsletters. The newsletter is distributed every second 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:
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:
 
 
 
You can see older newsletters here: [[Documentation/WhatsUpDoc_Archive]]
 
  
 
==== Distribution List ====
 
==== Distribution List ====
* OpenStack Docs Mailing List <Openstack-docs@lists.openstack.org>
 
 
* OpenStack Development Mailing List <openstack-dev@lists.openstack.org>
 
* OpenStack Development Mailing List <openstack-dev@lists.openstack.org>
 
* Docs liaisons (from https://wiki.openstack.org/wiki/CrossProjectLiaisons#Documentation)
 
* Docs liaisons (from https://wiki.openstack.org/wiki/CrossProjectLiaisons#Documentation)
 
* i18n List <openstack-i18n@lists.openstack.org>
 
* i18n List <openstack-i18n@lists.openstack.org>
  
==== Your suggestions for content ====
+
==== Content Sources ====
* Add
 
* Your
 
* Content
 
* Here
 
  
= 24 July 2015 =
+
Speciality team reports are gathered in the docs meeting every two weeks. If you are a speciality team leader and can't attend the  meeting, please either send a proxy to the meeting, or email your report to the meeting chair ahead of time.
  
Hi everyone,
+
If you have something that you would like to add to the next newsletter, please add it here:
  
I'm very pleased to announce that we finally have a name for our M release: Mitaka (三鷹)! Accordingly, the Tokyo Summit for the Mitaka release is only just over 100 days away. CFP closed a couple of days ago, and I've noticed that the first round of ATC discount codes have gone out. If you haven't got yours yet, then keep patching Liberty and sit tight. The discount codes will come out in stages after every snapshot. This week, we've had some great discussions about networking scenarios in the Install Guide, and the best way to include RST files in our newly converted books. We also have both the HA Guide and the Cloud Admin Guide conversions in their final stages, and the Install Guide conversion sprint coming up. Very exciting!
+
*
  
== Progress towards Liberty ==
+
==== Looking for older editions? ====
 
+
You can see older newsletters here: [[Documentation/WhatsUpDoc_Archive]]
* RST conversion:
 
** Install Guide: Conversion is now underway, sign up here: https://wiki.openstack.org/wiki/Documentation/Migrate#Installation_Guide_Migration
 
** Cloud Admin Guide: is nearly done. Sign up here: https://wiki.openstack.org/wiki/Documentation/Migrate#Cloud_Admin_Guide_Migration
 
** HA Guide: is also nearly done. Get in touch with Meg or Matt: https://wiki.openstack.org/wiki/Documentation/HA_Guide_Update
 
** Security Guide: Spec has merged. Planning is happening here: https://etherpad.openstack.org/p/sec-guide-rst
 
 
 
* 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
 
** Work has stalled on the Ironic docs, we need to pick this up again. Contact me if you want to know more, or are willing to help out.
 
 
 
* Improve how we communicate with and support our corporate contributors
 
** I have been brainstorming ideas with Foundation, watch this space!
 
 
 
* Improve communication with Docs Liaisons
 
** I'm very pleased to see liaisons getting more involved in our bugs and reviews. Keep up the good work!
 
 
 
* Clearing out old bugs
 
** A small amount of progress on the old bugs we held over from last week. New ones to check out in this newsletter!
 
 
 
== RST Migration ==
 
 
 
The next books we are focusing on for RST conversion are the Install Guide, Cloud Admin Guide, HA Guide, and the Security Guide. If you would like to assist, please get in touch with the appropriate speciality team:
 
 
 
* Install Guide:
 
** Contact Karin Levenstein <karin.levenstein@rackspace.com>
 
** Sign up here: https://wiki.openstack.org/wiki/Documentation/Migrate#Installation_Guide_Migration
 
** There's a sprint happening on this book later next week. Info and sign up here: https://wiki.openstack.org/wiki/VirtualSprints#Installation_guide_conversion_from_DocBook_to_RST
 
 
 
* Cloud Admin Guide:
 
** Contact Brian Moss <kallimachos@gmail.com> & Joseph Robinson <joseph.r.email@gmail.com>
 
** Sign up to help out here: https://wiki.openstack.org/wiki/Documentation/Migrate#Cloud_Admin_Guide_Migration
 
 
 
* HA Guide
 
** Contact Meg McRoberts <dreidellhasa@yahoo.com> or Matt Griffin <me@mattgriffin.com>
 
** Blueprint: https://blueprints.launchpad.net/openstack-manuals/+spec/improve-ha-guide
 
 
 
* Security Guide
 
** Contact Nathaniel Dillon <nathaniel.dillon@hp.com>
 
** Bug: https://bugs.launchpad.net/openstack-manuals/+bug/1463111
 
** Info: https://etherpad.openstack.org/p/sec-guide-rst
 
 
 
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.
 
 
 
== Install Guide RST Conversion Sprint ==
 
 
 
In order to kick off the RST conversion of the Install Guide, the speciality team have decided to run a virtual conversion sprint over two days on July 22-24. For more information, see the https://wiki.openstack.org/wiki/VirtualSprints#Installation_guide_conversion_from_DocBook_to_RST wiki page, and the https://etherpad.openstack.org/p/installguide-rst-virtual-sprint etherpad.
 
 
 
== HA Guide Works ==
 
 
 
With the RST conversion on the HA Guide wrapping up, the HA Guide speciality team are looking for people to help out with the reorganisation and writing the new content. They have quite a few bugs to get through, and they need your help! Contact Matt Griffin, or any other member of the HA Guide Speciality Team, or join their weekly IRC meeting. Details here: https://wiki.openstack.org/wiki/Documentation/HA_Guide_Update
 
 
 
== Docs Tools ==
 
 
 
Last week, we released openstackdocstheme 1.1.0, see http://lists.openstack.org/pipermail/openstack-announce/2015-June/000392.html. The main new features in this release are improvements for bug reporting, variable lists like the glossary are now indented, and next/prev links are now icons on the upper right part of the page.
 
 
 
Additionally, the stable/icehouse branch of openstack-manuals has been EOLed, no further updates will be done from it. For more information, see  
 
http://lists.openstack.org/pipermail/openstack-infra/2015-July/002888.html
 
 
 
== Doc team meeting ==
 
 
 
The next meetings are:
 
 
 
APAC: Wednesday 22 July, 00:30:00 UTC
 
 
 
US: Wednesday 29 July, 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
 
 
 
== Spotlight bugs for this week ==
 
 
 
We've now got people assigned to work on last week's old bugs, which is great! Here are three more rusty old bugs that could use some love:
 
 
 
https://bugs.launchpad.net/openstack-manuals/+bug/1241116 Using policies for protected properties
 
 
 
https://bugs.launchpad.net/openstack-manuals/+bug/1241179 Add notifications for groups and roles
 
 
 
https://bugs.launchpad.net/openstack-manuals/+bug/1251060 Xenapi: Allow windows builds with xentools 6.1 and 6.2
 
 
 
--
 
 
 
Remember, if you have content you would like to add to this newsletter, or you would like to be added to the distribution list, please email me directly at openstack@lanabrindley.com, or visit: https://wiki.openstack.org/w/index.php?title=Documentation/WhatsUpDoc
 
 
 
Keep on doc'ing!
 
 
 
Lana
 
 
 
= 17 July 2015 =
 
 
 
Hi everyone,
 
 
 
I'm very pleased to announce that we finally have a name for our M release: Mitaka (三鷹)! Accordingly, the Tokyo Summit for the Mitaka release is only just over 100 days away. CFP closed a couple of days ago, and I've noticed that the first round of ATC discount codes have gone out. If you haven't got yours yet, then keep patching Liberty and sit tight. The discount codes will come out in stages after every snapshot. This week, we've had some great discussions about networking scenarios in the Install Guide, and the best way to include RST files in our newly converted books. We also have both the HA Guide and the Cloud Admin Guide conversions in their final stages, and the Install Guide conversion sprint coming up. Very exciting!
 
 
 
== Progress towards Liberty ==
 
 
 
* RST conversion:
 
** Install Guide: Conversion is now underway, sign up here: https://wiki.openstack.org/wiki/Documentation/Migrate#Installation_Guide_Migration
 
** Cloud Admin Guide: is nearly done. Sign up here: https://wiki.openstack.org/wiki/Documentation/Migrate#Cloud_Admin_Guide_Migration
 
** HA Guide: is also nearly done. Get in touch with Meg or Matt: https://wiki.openstack.org/wiki/Documentation/HA_Guide_Update
 
** Security Guide: Spec has merged. Planning is happening here: https://etherpad.openstack.org/p/sec-guide-rst
 
 
 
* 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
+
= 7 April 2017 =
** Work has stalled on the Ironic docs, we need to pick this up again. Contact me if you want to know more, or are willing to help out.
 
  
* Improve how we communicate with and support our corporate contributors
+
Team,
** I have been brainstorming ideas with Foundation, watch this space!
 
  
* Improve communication with Docs Liaisons
+
This week I have still been working on drafting a governance tag for our guides called "docs:follows-policy". I have been working with Doug Hellmann (dhellmann) in the last week to change to draft dramatically, so it would be good for docs people to review again. We are trying to make this a more broad tag now, so it can be applied for other guides too. To review: https://review.openstack.org/#/c/445536/ I am also in the process of documenting guidelines in our Contribution Guide - which would also benefit from doc reviews:  https://review.openstack.org/#/c/453642/
** I'm very pleased to see liaisons getting more involved in our bugs and reviews. Keep up the good work!
 
  
* Clearing out old bugs
+
Would like to call out and thank John Davidge for his awesome work with the Networking Guide and neutron-related patches. He's been providing valuable guidance, and reviews, and it has been greatly appreciated by myself and the team.
** A small amount of progress on the old bugs we held over from last week. New ones to check out in this newsletter!
 
  
== RST Migration ==
+
Lana Brindley has done an awesome job for the last two weeks in keeping our bug list under control. We are down to an amazing 102 bugs in queue, and 82 bugs closed this cycle already!
 +
Next week, I will be looking after the bug triage liaison role!
 +
If you're sitting there thinking "bugs are for me, I really love triaging bugs!" well, you're in luck! We have one spot open for the rest of the cycle (14 Aug - 28 Aug): https://wiki.openstack.org/wiki/Documentation/SpecialityTeams#Bug_Triage_Team
  
The next books we are focusing on for RST conversion are the Install Guide, Cloud Admin Guide, HA Guide, and the Security Guide. If you would like to assist, please get in touch with the appropriate speciality team:
+
== The Road to the Summit in Boston ==
  
* Install Guide:
+
Keep an eye out for the docs and I18n have a project onboarding room at the summit. Melvin Hillsman (mrhillsman) of the User Committee submitted a forum topic for the Ops Guide to get operator feedback.
** Contact Karin Levenstein <karin.levenstein@rackspace.com>
+
David Flanders from the Foundation has also proposed a forum topic for developer.openstack.org (which currently houses our API, SDK, and other dev stuff). We'll be discussing major changes to that and would like to see some feedback from people here. Any questions on that, shoot it my way. My main objective for this forum topic is to reduce our current technical debt that lives on this site.
** Sign up here: https://wiki.openstack.org/wiki/Documentation/Migrate#Installation_Guide_Migration
+
For more information on forum topics: https://wiki.openstack.org/wiki/Forum
** There's a sprint happening on this book later next week. Info and sign up here: https://wiki.openstack.org/wiki/VirtualSprints#Installation_guide_conversion_from_DocBook_to_RST
+
Schedule has been released: https://www.openstack.org/summit/boston-2017/summit-schedul
  
* Cloud Admin Guide:
+
== Speciality Team Reports ==
** Contact Brian Moss <kallimachos@gmail.com> & Joseph Robinson <joseph.r.email@gmail.com>
 
** Sign up to help out here: https://wiki.openstack.org/wiki/Documentation/Migrate#Cloud_Admin_Guide_Migration
 
  
* HA Guide
+
* API - Anne Gentle: API versioning in relation to release versioning is currently manually compiled for the 40-ish API services, so ideas on how to automate and surface that info welcomed. More info: http://lists.openstack.org/pipermail/openstack-dev/2017-March/114690.html
** Contact Meg McRoberts <dreidellhasa@yahoo.com> or Matt Griffin <me@mattgriffin.com>
+
* Configuration Reference and CLI Reference - Tomoyuki Kato: N/A
** Blueprint: https://blueprints.launchpad.net/openstack-manuals/+spec/improve-ha-guide
+
* High Availability Guide - Ianeta Hutchinson: We are continuing to collaborate with OS DevOps team. See the tag ha-guide-draft for bugs opened to fill content for the new guide.
 
+
* Hypervisor Tuning Guide - Blair Bethwaite: N/A
* Security Guide
+
* Installation guides - Lana Brindley: We have now branched, so please remember to backport if you have edits to the Ocata guide now. Big thanks to all the testers who have been working hard over the past month or two (that Nova cells bug was *tough*!), and to Brian and Mariia for doing the heavy lifting. Noticed a bunch links to draft versions of the guide in Newton/Ocata branches, backports for that have been merged, and the Contributor Guide updated so we don't miss it in the future (https://docs.openstack.org/contributor guide/release/taskdetail.html#update-links-in-all-books).
** Contact Nathaniel Dillon <nathaniel.dillon@hp.com>
+
* Networking Guide - John Davidge: More patches landed in the last couple of weeks dealing with the move to OSC, and more are still in flight. Progress also continues on RFC 5737 compliance. Thanks to all contributors for their work.
** Bug: https://bugs.launchpad.net/openstack-manuals/+bug/1463111
+
* Operations and Architecture Design guides - Darren Chan: Arch Guide: edited architecture considerations content and cleaned up the index page structure which was applied across OS manuals. Some ops-related content was moved to the Ops Guide. Our current focus is improving the storage design content and networking design content.
** Info: https://etherpad.openstack.org/p/sec-guide-rst
+
* Training Guides - Matjaz Pancur: N/A
 
+
* Training labs - Roger Luethi: We released the Ocata version of training-labs this week.
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.
+
* User guides - Joseph Robinson: For the user guides - the spec on migrating the Admin Guide content this week moved closer to merging. I started preparing the work items for action on the User Guides tasks wiki page.
 
+
* Theme and Tools - Brian Moss: Anne has a spec up for theme consolidation, please check it out: https://review.openstack.org/#/c/454346/, Brian has fixed up the sitemap tool tests, reviews welcome: https://review.openstack.org/#/c/453976/. 41 open bugs, 13 closed in Pike
== Install Guide RST Conversion Sprint ==
 
 
 
In order to kick off the RST conversion of the Install Guide, the speciality team have decided to run a virtual conversion sprint over two days on July 22-24. For more information, see the https://wiki.openstack.org/wiki/VirtualSprints#Installation_guide_conversion_from_DocBook_to_RST wiki page, and the https://etherpad.openstack.org/p/installguide-rst-virtual-sprint etherpad.
 
 
 
== HA Guide Works ==
 
 
 
With the RST conversion on the HA Guide wrapping up, the HA Guide speciality team are looking for people to help out with the reorganisation and writing the new content. They have quite a few bugs to get through, and they need your help! Contact Matt Griffin, or any other member of the HA Guide Speciality Team, or join their weekly IRC meeting. Details here: https://wiki.openstack.org/wiki/Documentation/HA_Guide_Update
 
 
 
== Docs Tools ==
 
 
 
Last week, we released openstackdocstheme 1.1.0, see http://lists.openstack.org/pipermail/openstack-announce/2015-June/000392.html. The main new features in this release are improvements for bug reporting, variable lists like the glossary are now indented, and next/prev links are now icons on the upper right part of the page.
 
 
 
Additionally, the stable/icehouse branch of openstack-manuals has been EOLed, no further updates will be done from it. For more information, see
 
http://lists.openstack.org/pipermail/openstack-infra/2015-July/002888.html
 
  
 
== Doc team meeting ==
 
== Doc team meeting ==
 +
 +
Our next meeting will be on Thursday, 20 April at 2100 UTC in #openstack-meeting-alt.
 +
For more meeting details, including minutes and the agenda: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting
 +
The meeting chair will be me!
  
The next meetings are:
+
Big thanks to Joseph for stepping up in the last 2 meetings and hosting in my absence! Really appreciated it :)
 
 
APAC: Wednesday 22 July, 00:30:00 UTC
 
 
 
US: Wednesday 29 July, 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
 
 
 
== Spotlight bugs for this week ==
 
 
 
We've now got people assigned to work on last week's old bugs, which is great! Here are three more rusty old bugs that could use some love:
 
 
 
https://bugs.launchpad.net/openstack-manuals/+bug/1241116 Using policies for protected properties
 
 
 
https://bugs.launchpad.net/openstack-manuals/+bug/1241179 Add notifications for groups and roles
 
 
 
https://bugs.launchpad.net/openstack-manuals/+bug/1251060 Xenapi: Allow windows builds with xentools 6.1 and 6.2
 
  
 
--
 
--
 +
 +
Have a great week :)
 +
 +
Alex
  
Remember, if you have content you would like to add to this newsletter, or you would like to be added to the distribution list, please email me directly at openstack@lanabrindley.com, or visit: https://wiki.openstack.org/w/index.php?title=Documentation/WhatsUpDoc
+
IRC: asettle
 
+
Twitter: dewsday
Keep on doc'ing!
 
 
 
Lana
 
 
 
= 10 July 2015 =
 
 
 
Hi everyone,
 
  
First of all, apologies for my absence over the past couple of weeks. I took some time off to spend with my daughter while she was on school holidays, and then got ill! It never rains but it pours ;) While I was out, our M release was named, and then unnamed, and we're now waiting for a new name. We also had a great discussion about which networking scenario is the best fit for our new-and-improved Installation Guide, and planned a sprint to get the RST conversion for that book happening. More on that in this newsletter.
+
= 27 March 2017 =
  
== Progress towards Liberty ==
+
Team team team team team,
  
* RST conversion:
+
Well the last month has just FLOWN by since the PTG. We've got plenty going on in the docs team...
** Install Guide: Conversion is now underway, sign up here: https://wiki.openstack.org/wiki/Documentation/Migrate#Installation_Guide_Migration
 
** Cloud Admin Guide: is nearly done. Sign up here: https://wiki.openstack.org/wiki/Documentation/Migrate#Cloud_Admin_Guide_Migration
 
** HA Guide: is also underway. Get in touch with Meg or Matt: https://wiki.openstack.org/wiki/Documentation/HA_Guide_Update
 
** Security Guide: In planning. Stand by for more info.
 
  
* User Guides information architecture overhaul
+
This week I have been helping out the security team with the Security Guide. We've been working on some cursory edits, and removal of content. A few patches have already made it through - thanks to the OSIC security team for tackling some of the outstanding bugs. There'll be more edits coming from me in the next few weeks. To see our planning: https://etherpad.openstack.org/p/sec-guide-pike
** Waiting on the RST conversion of the Cloud Admin Guide to be complete
+
I am also in the process of drafting a governance tag for our install guides. Would be great for everyone to review and understand what the process will involve: https://review.openstack.org/#/c/445536/
  
* Greater focus on helping out devs with docs in their repo
+
Shoutout and big thanks to Brian Moss and the nova team who worked together tirelessly to document Nova v2 Cells and Placement API - which was a massive blocker for our Installation Guide.
** Work has started on the Ironic docs, we're now trying to resolve some issues with service name standards ("Bare Metal" or "Bare metal"?). Contact me if you want to know more, or are willing to help out.
 
  
* Improve how we communicate with and support our corporate contributors
+
Also, thank you to our Ocata release managers, Maria Zlatkova and Brian Moss for cutting the branch! Pike is well and truly underway now.
** I have been brainstorming ideas with Foundation, watch this space!
 
  
* Improve communication with Docs Liaisons
+
Ianeta Hutchinson has done an awesome job for the last two weeks in keeping our bug list under control. We are down to an amazing 104 bugs in queue, and 59 bugs closed this cycle already!
** I'm very pleased to see liaisons getting more involved in our bugs and reviews. Keep up the good work!
 
  
* Clearing out old bugs
+
Next week, we have Lana who will be looking after the bug triage liaison role!
** Sadly, no progress this week.
+
If you're sitting there thinking "bugs are for me, I really love triaging bugs!" well, you're in luck! We have a few spots open for the rest of the cycle: https://wiki.openstack.org/wiki/Documentation/SpecialityTeams#Bug_Triage_Team
  
== RST Migration ==
+
== The Road to the Summit in Boston ==
  
The next books we are focusing on for RST conversion are the Install Guide, Cloud Admin Guide, HA Guide, and the Security Guide. If you would like to assist, please get in touch with the appropriate speciality team:
+
* Schedule has been released: https://www.openstack.org/summit/boston-2017/summit-schedule/
 +
* Docs and I18n have a project onboarding room at the summit, keep an eye out on the dev ML for more information. Kendall will inform us when the time comes. Anyone around to help me with that? http://lists.openstack.org/pipermail/openstack-dev/2017-March/114149.html
 +
* Docs project update will be delivered by me (asettle) on Mon 8 , 3:40pm-4:20pm. https://www.openstack.org/summit/boston-2017/summit-schedule/global-search?t=Alexandra+Settle
  
* Install Guide:
+
== Speciality Team Reports ==
** Contact Karin Levenstein <karin.levenstein@rackspace.com>
 
** Sign up here: https://wiki.openstack.org/wiki/Documentation/Migrate#Installation_Guide_Migration
 
** There's a sprint happening on this book later this month. Info and sign up here: https://wiki.openstack.org/wiki/VirtualSprints#Installation_guide_conversion_from_DocBook_to_RST
 
  
* Cloud Admin Guide:
+
* API - Anne Gentle: There's still a lot of discussion on https://review.openstack.org/#/c/421846/ which is about API change guidelines. Take a look and join in on the review. Also on the openstack-dev list, there's a thread about the future of the app catalog, which is relevant to the app developer audience so I include it here: http://lists.openstack.org/pipermail/openstack dev/2017-March/113362.html Also related to the app dev audience is the wrapping up of the App Ecosystem working group: http://lists.openstack.org/pipermail/user-committee/2017-March/001825.html
** Contact Brian Moss <kallimachos@gmail.com> & Joseph Robinson <joseph.r.email@gmail.com>
+
* Configuration Reference and CLI Reference - Tomoyuki Kato: N/A
** Sign up to help out here: https://wiki.openstack.org/wiki/Documentation/Migrate#Cloud_Admin_Guide_Migration
+
* High Availability Guide - Ianeta Hutchinson: At the Atlanta PTG, the documentation team outlined a new table of contents that is now upstream as a draft here: https://github.com/openstack/openstack-manuals/tree/master/doc/ha-guide-draft. A blocker to progress in the past had been a lack of SME’s for the topic of high availability but that is no longer the case \o/. The OSIC DevOps team has an “adopt-a-guide” project in which they are collaborating with the OpenStack docs community and OSIC Docs team to apply the new ToC and validate all content for the guide. The progress of this collaboration is being tracked here <https://docs.google.com/spreadsheets/d/1hw4axU2IbLlsjKpz9_EGlKQt0S6siViik7ETjNg_MgI/edit?usp=sharing> We are calling for more contributors both as SME's and tech writers. Ping iphutch if interested!
 
+
* Hypervisor Tuning Guide - Blair Bethwaite: N/A
* HA Guide
+
* Installation guides - Lana Brindley: Cells bug is closer to being fixed, and we are closer to a complete test install (https://wiki.openstack.org/wiki/Documentation/NewtonDocTesting look at all that green!). We're planning to branch Ocata by the end of this week.
** Contact Meg McRoberts <dreidellhasa@yahoo.com> or Matt Griffin <me@mattgriffin.com>
+
* Networking Guide - John Davidge: N/A
** Blueprint: https://blueprints.launchpad.net/openstack-manuals/+spec/improve-ha-guide
+
* Operations and Architecture Design guides - Darren Chan: Arch Design Guide: Minor IA and general cleanup of the storage, compute, and networking sections in the Design chapter. Currently updating gaps in storage design content. Ops Guide: Removed cloud architecture content (migrated to the Arch Design Guide).
 
+
* Security Guide - Nathaniel Dillon: Edits from Alex going through, and patches from the OSIC DevOps team. See above for more info.
* Security Guide
+
* Training Guides - Matjaz Pancur: For Training guides related topics: a new brand for activities around OpenStack Upstream University/Training. It is now known as OpenStack Upstream Institute (https://wiki.openstack.org/wiki/OpenStack_Upstream_Institute)
** Contact Nathaniel Dillon <nathaniel.dillon@hp.com>
+
* Training labs - Roger Luethi: We are currently testing our automated version of the Ocata install-guide. We had a problem with Ubuntu's new ISO image (16.04.2 LTS) which is now resolved.
** Bug: https://bugs.launchpad.net/openstack-manuals/+bug/1463111
+
* User guides - Joseph Robinson: Several other Legacy commands were converted to OS commands this week. Reviewed the Admin Guide spec.
** Spec: https://review.openstack.org/#/c/196165/
+
* Theme and Tools - Brian Moss: I'd like to do an openstackdocstheme release soon, as we've got some items (PDF styling, search page JS fix, image centering) that would be good to have in production. Any concerns or last minute items to merge please let me know. We've had some issues come up with the auto-generation scripts. Some have been fixed already (thanks Kato and Christian!), and we're investigating others. If you notice anything amiss or would like to help out, please let me know. 46 open bugs, 8 closed in Pike
 
 
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.
 
 
 
== Install Guide RST Conversion Sprint ==
 
 
 
In order to kick off the RST conversion of the Install Guide, the speciality team have decided to run a virtual conversion sprint over two days on July 22-24. For more information, see the https://wiki.openstack.org/wiki/VirtualSprints#Installation_guide_conversion_from_DocBook_to_RST wiki page, and the https://etherpad.openstack.org/p/installguide-rst-virtual-sprint etherpad.
 
 
 
== New core team ==
 
 
 
The core team have just completed our review for July, and would like to welcome two new core contributors: Alexandra Settle, and Olena Logvinova. Congratulations to you both :)
 
  
 
== Doc team meeting ==
 
== Doc team meeting ==
 
+
The APAC meeting was cancelled this week, our next meetings are:
+
Our next meeting will be on Thursday, 7 April at 2100 UTC in #openstack-meeting-alt.
 
+
For more meeting details, including minutes and the agenda: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting
US: Wednesday 15 July, 14:00:00 UTC (note that this has NOT changed with daylight savings time)
 
APAC: Wednesday 22 July, 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
 
 
 
== Spotlight bugs for this week ==
 
 
 
Sadly, even with an extra week, our three spotlight bugs remain unloved. I'm going to keep them here for another week, so now is your chance to swoop in and make a difference!
 
 
 
https://bugs.launchpad.net/openstack-manuals/+bug/1212349 vmware documentation
 
 
 
https://bugs.launchpad.net/openstack-manuals/+bug/1212687 xenapi
 
 
 
https://bugs.launchpad.net/openstack-manuals/+bug/1239308 Add notifications for groups and roles
 
  
 
--
 
--
 +
 +
Have a great week :)
 +
 +
Alex
  
Remember, if you have content you would like to add to this newsletter, or you would like to be added to the distribution list, please email me directly at openstack@lanabrindley.com, or visit: https://wiki.openstack.org/w/index.php?title=Documentation/WhatsUpDoc
+
IRC: asettle
 
+
Twitter: dewsday
Keep on doc'ing!
 
 
 
Lana
 

Latest revision as of 17:37, 30 November 2017

Documentation Newsletters

This is where I draft the 'What's Up, Doc?' documentation newsletters. The newsletter is distributed every second 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

Content Sources

Speciality team reports are gathered in the docs meeting every two weeks. If you are a speciality team leader and can't attend the meeting, please either send a proxy to the meeting, or email your report to the meeting chair ahead of time.

If you have something that you would like to add to the next newsletter, please add it here:

Looking for older editions?

You can see older newsletters here: Documentation/WhatsUpDoc_Archive

7 April 2017

Team,

This week I have still been working on drafting a governance tag for our guides called "docs:follows-policy". I have been working with Doug Hellmann (dhellmann) in the last week to change to draft dramatically, so it would be good for docs people to review again. We are trying to make this a more broad tag now, so it can be applied for other guides too. To review: https://review.openstack.org/#/c/445536/ I am also in the process of documenting guidelines in our Contribution Guide - which would also benefit from doc reviews: https://review.openstack.org/#/c/453642/

Would like to call out and thank John Davidge for his awesome work with the Networking Guide and neutron-related patches. He's been providing valuable guidance, and reviews, and it has been greatly appreciated by myself and the team.

Lana Brindley has done an awesome job for the last two weeks in keeping our bug list under control. We are down to an amazing 102 bugs in queue, and 82 bugs closed this cycle already! Next week, I will be looking after the bug triage liaison role! If you're sitting there thinking "bugs are for me, I really love triaging bugs!" well, you're in luck! We have one spot open for the rest of the cycle (14 Aug - 28 Aug): https://wiki.openstack.org/wiki/Documentation/SpecialityTeams#Bug_Triage_Team

The Road to the Summit in Boston

Keep an eye out for the docs and I18n have a project onboarding room at the summit. Melvin Hillsman (mrhillsman) of the User Committee submitted a forum topic for the Ops Guide to get operator feedback. David Flanders from the Foundation has also proposed a forum topic for developer.openstack.org (which currently houses our API, SDK, and other dev stuff). We'll be discussing major changes to that and would like to see some feedback from people here. Any questions on that, shoot it my way. My main objective for this forum topic is to reduce our current technical debt that lives on this site. For more information on forum topics: https://wiki.openstack.org/wiki/Forum Schedule has been released: https://www.openstack.org/summit/boston-2017/summit-schedul

Speciality Team Reports

  • API - Anne Gentle: API versioning in relation to release versioning is currently manually compiled for the 40-ish API services, so ideas on how to automate and surface that info welcomed. More info: http://lists.openstack.org/pipermail/openstack-dev/2017-March/114690.html
  • Configuration Reference and CLI Reference - Tomoyuki Kato: N/A
  • High Availability Guide - Ianeta Hutchinson: We are continuing to collaborate with OS DevOps team. See the tag ha-guide-draft for bugs opened to fill content for the new guide.
  • Hypervisor Tuning Guide - Blair Bethwaite: N/A
  • Installation guides - Lana Brindley: We have now branched, so please remember to backport if you have edits to the Ocata guide now. Big thanks to all the testers who have been working hard over the past month or two (that Nova cells bug was *tough*!), and to Brian and Mariia for doing the heavy lifting. Noticed a bunch links to draft versions of the guide in Newton/Ocata branches, backports for that have been merged, and the Contributor Guide updated so we don't miss it in the future (https://docs.openstack.org/contributor guide/release/taskdetail.html#update-links-in-all-books).
  • Networking Guide - John Davidge: More patches landed in the last couple of weeks dealing with the move to OSC, and more are still in flight. Progress also continues on RFC 5737 compliance. Thanks to all contributors for their work.
  • Operations and Architecture Design guides - Darren Chan: Arch Guide: edited architecture considerations content and cleaned up the index page structure which was applied across OS manuals. Some ops-related content was moved to the Ops Guide. Our current focus is improving the storage design content and networking design content.
  • Training Guides - Matjaz Pancur: N/A
  • Training labs - Roger Luethi: We released the Ocata version of training-labs this week.
  • User guides - Joseph Robinson: For the user guides - the spec on migrating the Admin Guide content this week moved closer to merging. I started preparing the work items for action on the User Guides tasks wiki page.
  • Theme and Tools - Brian Moss: Anne has a spec up for theme consolidation, please check it out: https://review.openstack.org/#/c/454346/, Brian has fixed up the sitemap tool tests, reviews welcome: https://review.openstack.org/#/c/453976/. 41 open bugs, 13 closed in Pike

Doc team meeting

Our next meeting will be on Thursday, 20 April at 2100 UTC in #openstack-meeting-alt. For more meeting details, including minutes and the agenda: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting The meeting chair will be me!

Big thanks to Joseph for stepping up in the last 2 meetings and hosting in my absence! Really appreciated it :)

--

Have a great week :)

Alex

IRC: asettle Twitter: dewsday

27 March 2017

Team team team team team,

Well the last month has just FLOWN by since the PTG. We've got plenty going on in the docs team...

This week I have been helping out the security team with the Security Guide. We've been working on some cursory edits, and removal of content. A few patches have already made it through - thanks to the OSIC security team for tackling some of the outstanding bugs. There'll be more edits coming from me in the next few weeks. To see our planning: https://etherpad.openstack.org/p/sec-guide-pike I am also in the process of drafting a governance tag for our install guides. Would be great for everyone to review and understand what the process will involve: https://review.openstack.org/#/c/445536/

Shoutout and big thanks to Brian Moss and the nova team who worked together tirelessly to document Nova v2 Cells and Placement API - which was a massive blocker for our Installation Guide.

Also, thank you to our Ocata release managers, Maria Zlatkova and Brian Moss for cutting the branch! Pike is well and truly underway now.

Ianeta Hutchinson has done an awesome job for the last two weeks in keeping our bug list under control. We are down to an amazing 104 bugs in queue, and 59 bugs closed this cycle already!

Next week, we have Lana who will be looking after the bug triage liaison role! If you're sitting there thinking "bugs are for me, I really love triaging bugs!" well, you're in luck! We have a few spots open for the rest of the cycle: https://wiki.openstack.org/wiki/Documentation/SpecialityTeams#Bug_Triage_Team

The Road to the Summit in Boston

Speciality Team Reports

  • API - Anne Gentle: There's still a lot of discussion on https://review.openstack.org/#/c/421846/ which is about API change guidelines. Take a look and join in on the review. Also on the openstack-dev list, there's a thread about the future of the app catalog, which is relevant to the app developer audience so I include it here: http://lists.openstack.org/pipermail/openstack dev/2017-March/113362.html Also related to the app dev audience is the wrapping up of the App Ecosystem working group: http://lists.openstack.org/pipermail/user-committee/2017-March/001825.html
  • Configuration Reference and CLI Reference - Tomoyuki Kato: N/A
  • High Availability Guide - Ianeta Hutchinson: At the Atlanta PTG, the documentation team outlined a new table of contents that is now upstream as a draft here: https://github.com/openstack/openstack-manuals/tree/master/doc/ha-guide-draft. A blocker to progress in the past had been a lack of SME’s for the topic of high availability but that is no longer the case \o/. The OSIC DevOps team has an “adopt-a-guide” project in which they are collaborating with the OpenStack docs community and OSIC Docs team to apply the new ToC and validate all content for the guide. The progress of this collaboration is being tracked here <https://docs.google.com/spreadsheets/d/1hw4axU2IbLlsjKpz9_EGlKQt0S6siViik7ETjNg_MgI/edit?usp=sharing> We are calling for more contributors both as SME's and tech writers. Ping iphutch if interested!
  • Hypervisor Tuning Guide - Blair Bethwaite: N/A
  • Installation guides - Lana Brindley: Cells bug is closer to being fixed, and we are closer to a complete test install (https://wiki.openstack.org/wiki/Documentation/NewtonDocTesting look at all that green!). We're planning to branch Ocata by the end of this week.
  • Networking Guide - John Davidge: N/A
  • Operations and Architecture Design guides - Darren Chan: Arch Design Guide: Minor IA and general cleanup of the storage, compute, and networking sections in the Design chapter. Currently updating gaps in storage design content. Ops Guide: Removed cloud architecture content (migrated to the Arch Design Guide).
  • Security Guide - Nathaniel Dillon: Edits from Alex going through, and patches from the OSIC DevOps team. See above for more info.
  • Training Guides - Matjaz Pancur: For Training guides related topics: a new brand for activities around OpenStack Upstream University/Training. It is now known as OpenStack Upstream Institute (https://wiki.openstack.org/wiki/OpenStack_Upstream_Institute)
  • Training labs - Roger Luethi: We are currently testing our automated version of the Ocata install-guide. We had a problem with Ubuntu's new ISO image (16.04.2 LTS) which is now resolved.
  • User guides - Joseph Robinson: Several other Legacy commands were converted to OS commands this week. Reviewed the Admin Guide spec.
  • Theme and Tools - Brian Moss: I'd like to do an openstackdocstheme release soon, as we've got some items (PDF styling, search page JS fix, image centering) that would be good to have in production. Any concerns or last minute items to merge please let me know. We've had some issues come up with the auto-generation scripts. Some have been fixed already (thanks Kato and Christian!), and we're investigating others. If you notice anything amiss or would like to help out, please let me know. 46 open bugs, 8 closed in Pike

Doc team meeting

Our next meeting will be on Thursday, 7 April at 2100 UTC in #openstack-meeting-alt. For more meeting details, including minutes and the agenda: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

--

Have a great week :)

Alex

IRC: asettle Twitter: dewsday