Jump to: navigation, search

Difference between revisions of "Documentation/WhatsUpDoc"

(27 May 2016)
m
 
(108 intermediate revisions by 2 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 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 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 ====
 
==== 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)
Line 10: Line 9:
 
==== Content Sources ====
 
==== Content Sources ====
  
Speciality team reports are gathered here: https://etherpad.openstack.org/p/Speciality_Team_Reports
+
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.
  
* Your
+
If you have something that you would like to add to the next newsletter, please add it here:
* Content
+
 
* Here
+
*  
* api-site bugs have been cleaned up. The only bugs listed there now  are either for API Quick Start or the First App on OpenStack. Thanks Atsushi-san and Anne.
 
  
 
==== Looking for older editions? ====
 
==== Looking for older editions? ====
 
You can see older newsletters here: [[Documentation/WhatsUpDoc_Archive]]
 
You can see older newsletters here: [[Documentation/WhatsUpDoc_Archive]]
  
= 27 May 2016 =
+
= 7 April 2017 =
 
 
Hi everyone,
 
  
This week I've been focused on getting the Install Guide project back up and running, with the team meeting being rebooted, our specs finally merged, and organising the list of tasks to be getting on with. Also: don't forget to vote in our naming poll: [link redacted for wiki] I'm still very much in need of representatives from the various project teams to pitch in and help us get things running. Please make sure your project is represented by coming along to meetings, or at least contacting us through the mailing list.
+
Team,
  
In other news, the Ops and Arch Guide re-architecture is proceeding apace. Specs were merged this week, and the new Arch Guide ToC is looking great! Check it out here: http://specs.openstack.org/openstack/docs-specs/specs/newton/arch-guide-restructure.html We are also still looking for feedback on the current Ops guide. Add your notes here: https://etherpad.openstack.org/p/ops-guide-reorg
+
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/
  
== Progress towards Newton ==
+
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.
  
131 days to go!
+
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
  
Bugs closed so far: 107
+
== The Road to the Summit in Boston ==
  
Newton deliverables https://wiki.openstack.org/wiki/Documentation/NewtonDeliverables
+
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.
Feel free to add more detail and cross things off as they are achieved throughout the release. I will also do my best to ensure it's kept up to date for each newsletter.
+
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 ==
 
== Speciality Team Reports ==
  
'''HA Guide: Bogdan Dobrelya'''
+
* 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
No report this week.
+
* 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.
'''Install Guide: Lana Brindley'''
+
* Hypervisor Tuning Guide - Blair Bethwaite: N/A
Specs are now merged, an blueprints created. Tasks listed here: https://wiki.openstack.org/wiki/Documentation/InstallGuideWorkItems Please go ahead and pick up work items. Need project representation in meetings. Next meeting: Tue 7 June 0600 UTC
+
* 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.
'''Networking Guide: Edgar Magana'''
+
* 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.
We did not have meeting this week. Nothing to report. Next IRC meeting: Thursday June 2nd at 1600 UTC
+
* Training Guides - Matjaz Pancur: N/A
 
+
* Training labs - Roger Luethi: We released the Ocata version of training-labs this week.
'''Security Guide: Nathaniel Dillon'''
+
* 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.
No report this week.
+
* 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
 
 
'''User Guides: Joseph Robinson'''
 
No report this week.
 
 
 
'''Ops Guide: Shilla Saebi'''
 
Shilla & Darren working on collecting enterprise docs to push upstream
 
Ops tasks are documented here: https://etherpad.openstack.org/p/ops-arch-tasks
 
OpenStack ops guide reorg in progress & documented here: https://etherpad.openstack.org/p/ops-guide-reorg
 
Spec was merged: https://review.openstack.org/#/c/311998/
 
 
 
'''API Guide: Anne Gentle'''
 
No report this week.
 
 
 
'''Config/CLI Ref: Tomoyuki Kato'''
 
A few configuration docs patches for some vendor plug-ins has been merged, with mitaka backport.
 
Heat CLI is marked as deprecated.
 
 
 
'''Training labs: Pranav Salunke, Roger Luethi'''
 
No report this week.
 
 
 
'''Training Guides: Matjaz Pancur'''
 
Updates for Upstream training material
 
 
 
'''Hypervisor Tuning Guide: Blair Bethwaite
 
No report this week.
 
 
 
'''UX/UI Guidelines: Michael Tullis, Stephen Ballard'''
 
No report this week.
 
 
 
== Site Stats ==
 
 
 
This month, two thirds of our site visitors have been using their Mac to read the docs. Just under 30% used Windows, and Linux rounded out the remainder at 4%.
 
 
 
So far Install Guide naming poll, "OpenStack Installation Tutorial" has a commanding lead at 30%, with "Basic Install Guide" and "OpenStack Evaluation Setup Guide" (try saying that ten times fast!) tying for second place with 17% of the vote each. I'll keep the poll open for another week or so, and announce our winning name in next week's newsletter.
 
  
 
== 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!
  
Next meetings:
+
Big thanks to Joseph for stepping up in the last 2 meetings and hosting in my absence! Really appreciated it :)
 
 
The US meeting was held this week, you can read the minutes here: https://wiki.openstack.org/wiki/Documentation/MeetingLogs#2016-05-25
 
 
 
Next meetings:
 
APAC: Wednesday 1 June, 00:30 UTC
 
US: Wednesday 8 June, 19: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
 
  
 
--
 
--
 +
 +
Have a great week :)
 +
 +
Alex
  
Keep on doc'ing!
+
IRC: asettle
 +
Twitter: dewsday
  
Lana
+
= 27 March 2017 =
  
https://wiki.openstack.org/wiki/Documentation/WhatsUpDoc#27_May_2016
+
Team team team team team,
  
= 20 May 2016 =
+
Well the last month has just FLOWN by since the PTG. We've got plenty going on in the docs team...
  
Hi everyone,
+
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/
  
I've been struck down by the dreaded flu this week, so it's been a bit quiet around here. I have, however, crawled out from under the tissues, throat lozenges, and episodes of Containment to pen my regular newsletter for you. See how dedicated I am to the cause? ;)
+
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.
  
The biggest updates this week have been on the API side of the ship, with the api-site bug list cleared out. Well done to Anne and Atsushi-san for the heavy lifting there. We also saw a lot of speciality team meetings kick off again this week, with more coming next week, so keep an eye on the mailing list and your ical for the projects you're interested in. We have also now hit our stride on the regular docs meetings, with the APAC meeting held this week, and the US one rolling around again next week. If you're a docs cross-project liaison, make sure you check out the timing and pick one that works for you, so we can make sure we're discussing *your* project.
+
Also, thank you to our Ocata release managers, Maria Zlatkova and Brian Moss for cutting the branch! Pike is well and truly underway now.
  
== Progress towards Newton ==
+
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!
  
138 days to go!
+
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
  
Bugs closed so far: 89
+
== The Road to the Summit in Boston ==
  
Newton deliverables https://wiki.openstack.org/wiki/Documentation/NewtonDeliverables
+
* Schedule has been released: https://www.openstack.org/summit/boston-2017/summit-schedule/
Feel free to add more detail and cross things off as they are achieved throughout the release. I will also do my best to ensure it's kept up to date for each newsletter.
+
* 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
  
 
== Speciality Team Reports ==
 
== Speciality Team Reports ==
  
'''HA Guide: Bogdan Dobrelya'''
+
* 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
No report this week.
+
* 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!
'''Install Guide: Lana Brindley'''
+
* Hypervisor Tuning Guide - Blair Bethwaite: N/A
Meetings start up next week: http://eavesdrop.openstack.org/#Documentation_Install_Team_Meeting
+
* 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.
Cookie cutter has been merged, repo here: http://git.openstack.org/cgit/openstack/installguide-cookiecutter/
+
* Networking Guide - John Davidge: N/A
Need to merge spec: https://review.openstack.org/#/c/310588
+
* 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.
'''Networking Guide: Edgar Magana'''
+
* 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)
We have successfully changedthe bi-weekly meeting schedule from odd to even weeks.
+
* 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.
There will not be meetingthis week. Next meeting will be on June 2nd.
+
* 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
'''Security Guide: Nathaniel Dillon'''
 
No report this week.
 
 
 
'''User Guides: Joseph Robinson'''
 
Team Meeting restarted - Just me this week, I'll send a summary to the mailing list to keep everyone up to date, and if anyone is interested in joining in.
 
Python SDK file moving - one item left from the Mitaka patch - Finding a location to move these files - dev and doc mailing list email forthcoming on where to put these files.
 
 
 
'''Ops Guide: Shilla Saebi'''
 
No report this week.
 
 
 
'''API Guide: Anne Gentle'''
 
The extension, os-api-ref, is now available via Pypi so that all projects can re-use it with test-requirements.txt. Thanks Sean Dague for this effort!
 
Several projects have reviews in progress for their API reference conversion: glance https://review.openstack.org/#/c/312259/, manila https://review.openstack.org/#/c/313874, neutron https://review.openstack.org/#/c/314819, swift https://review.openstack.org/#/c/312315/, trove https://review.openstack.org/#/c/316381. (There are probably more but those are on my radar).
 
Please review the response code table at https://review.openstack.org/#/c/318281/ and http://i.imgur.com/onsRFtI.png for your use cases for API reference docs.
 
 
 
'''Config/CLI Ref: Tomoyuki Kato'''
 
No report this week.
 
 
 
'''Training labs: Pranav Salunke, Roger Luethi'''
 
No report this week.
 
 
 
'''Training Guides: Matjaz Pancur'''
 
Work on the slides for Training guides (https://review.openstack.org/#/c/295016/)
 
Feedback about Upstream training in Austin (see http://eavesdrop.openstack.org/meetings/training_guides/2016/training_guides.2016-05-16-17.02.html)
 
 
 
'''Hypervisor Tuning Guide: Blair Bethwaite
 
Hi! I'm going to try looking after this for a while as Joe focusses on other things. Not promising much at this point beyond a little wiki gardening, but longer term I hope to align it with some activities in the scientific-wg (which I'm co-chairing with Stig Telfer), and it will probably become a point of reference for some of the activities we already have planned this cycle.
 
 
 
'''UX/UI Guidelines: Michael Tullis, Stephen Ballard'''
 
No report this week.
 
 
 
== Site Stats ==
 
 
 
While 90% of our readers have their browsers set to US English, just under 8% browse in Chinese, and a mere 0.15% use British English. That last one might be just me ;)
 
  
 
== Doc team meeting ==
 
== Doc team meeting ==
 
+
Next meetings:
+
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
The APAC meeting was held this week, you can read the minutes here: https://wiki.openstack.org/wiki/Documentation/MeetingLogs#2016-05-18
 
 
 
Next meetings:
 
US: Wednesday 25 May, 19:00 UTC
 
APAC: Wednesday 1 June, 00:30 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
 
  
 
--
 
--
 +
 +
Have a great week :)
 +
 +
Alex
  
Keep on doc'ing!
+
IRC: asettle
 
+
Twitter: dewsday
Lana
 
 
 
https://wiki.openstack.org/wiki/Documentation/WhatsUpDoc#20_May_2016
 
 
 
= 13 May 2016 =
 
 
 
Hi everyone,
 
 
 
Wow, what a busy week! I've been mainly focused on the Install Guide speciality team this week, with gathering interested participants, ensuring our specs are ready to be merged, and setting a new meeting time. I'm also pleased to say that our speciality team reports make a post-Summit comeback in this newsletter.
 
 
 
Just another reminder that all projects should update their cross-project liaison for docs on the wiki here: https://wiki.openstack.org/wiki/CrossProjectLiaisons#Documentation If you're one of the lucky people nominated by your PTL to be a docs CPL, then please do your very best to attend docs meetings in your favourite timezone to make sure we hear the voice of your project when we're making documentation decisions. Details of upcoming docs meetings are at the end of this newsletter every week.
 
 
 
On a related note, it was refreshing to read the conversation from the US meeting this week, and the associated conversation on the mailing lists about developer contributions to documentation. We'd love to find out what it is that prevents you from contributing to the docs, and what the docs team can do to make things that little bit easier for you! Reach out to us either on the dev mailing list (with [docs] in the subject line), or on the docs mailing list at openstack-docs@lists.openstack.org.
 
 
 
== Progress towards Newton ==
 
 
 
145 days to go!
 
 
 
Bugs closed so far: 71
 
 
 
Newton deliverables https://wiki.openstack.org/wiki/Documentation/NewtonDeliverables
 
Feel free to add more detail and cross things off as they are achieved throughout the release. I will also do my best to ensure it's kept up to date for each newsletter.
 
 
 
The Ops and HA Guides now exist in openstack-manuals, and the old repos have now been set to read-only.
 
 
 
We also have the first patch in for the Install Guide 'cookie cutter' template, which is a great start!
 
 
 
== Speciality Team Reports ==
 
 
 
'''HA Guide: Bogdan Dobrelya'''
 
No report this week.
 
 
 
'''Install Guide: Lana Brindley'''
 
New meeting time proposed: https://review.openstack.org/#/c/314831/ Still need to merge final spec: https://review.openstack.org/#/c/310588/ If you're interested in helping out, add your name here: https://wiki.openstack.org/wiki/Documentation/InstallGuide#Team_members
 
 
 
'''Networking Guide: Edgar Magana'''
 
We are planning to resume the meeting next week.
 
 
 
'''Security Guide: Nathaniel Dillon'''
 
Summit Recap: https://etherpad.openstack.org/p/austin-docs-workgroup-security
 
Good conversations around API rate limiting, OSSN in-flight, SecGuide work being prep'd (Thanks to Luke Hinds for taking this on!)
 
Added Doc reviewer (Thanks Shilla and welcome!)
 
Will be focusing on Neutron security
 
 
 
'''User Guides: Joseph Robinson'''
 
No report this week.
 
 
 
'''Ops Guide: Shilla Saebi'''
 
Proposed architecture guide restructure: https://review.openstack.org/#/c/311998/
 
Ops guide session Etherpad from Austin: https://etherpad.openstack.org/p/AUS-ops-Docs-ops-guide
 
OpsGuide reorg: https://etherpad.openstack.org/p/PAO-ops-ops-guide-fixing
 
Newton Plans:
 
Review content of both guides, and delete anything out of date
 
Review architecture of both guides, and possibly combine
 
Ops Guide in openstack-manuals repo
 
Gather content from Ops internal documentation
 
 
 
'''API Guide: Anne Gentle'''
 
All but two services have someone working on landing a migration patch in the project's repo.
 
Read: Status on bugs and migration http://lists.openstack.org/pipermail/openstack-docs/2016-May/008624.html
 
Read: Summit session recap http://lists.openstack.org/pipermail/openstack-dev/2016-May/094472.html
 
 
 
'''Config/CLI Ref: Tomoyuki Kato'''
 
Discussing documenting auto generation of config options with Oslo team.
 
Dropped keystone command-line client from CLI reference.
 
Keystone CLI was removed in python-keystoneclient 3.0.0 release.
 
 
 
'''Training labs: Pranav Salunke, Roger Luethi'''
 
Working on adding new features like PXE boot.
 
Stabilizing current release and backends.
 
Figuring out the zip file generation and web site/page.
 
Chaging the meeting time to more CET/CEST friendly time.
 
 
 
'''Training Guides: Matjaz Pancur'''
 
No report this week.
 
 
 
'''Hypervisor Tuning Guide: Joe Topjian'''
 
No report this week.
 
 
 
'''UX/UI Guidelines: Michael Tullis, Stephen Ballard'''
 
No report this week.
 
 
 
== Site Stats ==
 
 
 
The interesting fact I'd like to share with you this week is that just over 25% of our viewers this month are new to the site.
 
 
 
== Doc team meeting ==
 
 
 
Next meetings:
 
 
 
The US meeting was held this week, you can read the minutes here: https://wiki.openstack.org/wiki/Documentation/MeetingLogs#2016-05-11
 
 
 
Next meetings:
 
APAC: Wednesday 18 May, 00:30 UTC
 
US: Wednesday 25 May, 19: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
 
 
 
--
 
 
 
Keep on doc'ing!
 
 
 
Lana
 
 
 
https://wiki.openstack.org/wiki/Documentation/WhatsUpDoc#13_May_2016
 
 
 
= 6 May 2016 =
 
 
 
Hi everyone,
 
 
 
I hope you all had a safe journey home from Summit, and are now fully recovered from all the excitement (and jetlag)! I'm really pleased with the amount of progress we made this time around. We have a definitive set of goals for Newton, and I'm confident that they're all moving us towards a much better docs suite overall. Of course, the biggest and most important work we have to do is to get our Install Guide changes underway. I'm very excited to see the new method for documenting OpenStack installation, and can't wait to see all our big tent projects contributing to docs in such a meaningful way. Thank you to everyone (in the room and online) who contributed to the Install Guide discussion, and helped us move forward on this important project.
 
 
 
In other news, I've written a wrapup of the Austin design summit on my blog, which you might be interested in: http://lanabrindley.com/2016/05/05/openstack-newton-summit-docs-wrapup/
 
 
 
== Progress towards Newton ==
 
 
 
152 days to go!
 
 
 
Bugs closed so far: 61
 
 
 
Because we have such a specific set of deliverables carved out for Newton, I've made them their own wiki page: https://wiki.openstack.org/wiki/Documentation/NewtonDeliverables
 
Feel free to add more detail and cross things off as they are achieved throughout the release. I will also do my best to ensure it's kept up to date for each newsletter.
 
 
 
One of the first tasks we've started work on after Summit is moving the Ops and HA Guides out of their own repositories and into openstack-manuals. As a result, those repositories are now frozen, and any work you want to do on those books should be in openstack-manuals.
 
 
 
We are almost ready to publish the new RST version of the Ops Guide, there's just a few cleanup edits going in now, so make sure you have the right book, in the right repo from now on. This was our very last book remaining in DocBook XML, so the docs toolchain will be removing DocBook XML support. See spec https://review.openstack.org/311698 for details.
 
 
 
Another migration note is that the API reference content is moving from api-site to project specific repositories and api-site is now frozen. For more detail, see Anne's email: http://lists.openstack.org/pipermail/openstack-docs/2016-May/008536.html
 
 
 
== Mitaka wrapup ==
 
 
 
We performed a Mitaka retrospective at Summit, notes are here: https://etherpad.openstack.org/p/austin-docs-mitakaretro
 
 
 
In particular, I'd like to call out our hard working tools team Andreas and Christian, all our Speciality Team leads, and the Mitaka release managers Brian and Olga. Well done on a very successful release, everyone :)
 
 
 
Total bugs closed: 645
 
 
 
== Site Stats ==
 
 
 
Thanks to the lovely people at Foundation (thanks Allison!) I now have access to more stats than I could possibly guess what to do with, and I'm hoping to be able to share some of these with you through the newsletter. If there's something in particular you would like to see, then please let me know and I'll endeavour to record it here!
 
 
 
So far I can tell you that docs.openstack.org had 1.63M unique pageviews in April, down slightly from 1.72M in March, and the average session duration is just over six minutes, looking at just under 4 pages per session.
 
 
 
== Doc team meeting ==
 
 
 
Next meetings:
 
 
 
We'll be restarting the meeting series next week.
 
 
 
Next meetings:
 
US: Wednesday 11 April, 19:00 UTC
 
APAC: Wednesday 18 April, 00:30 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
 
 
 
--
 
 
 
Keep on doc'ing!
 
 
 
Lana
 
 
 
https://wiki.openstack.org/wiki/Documentation/WhatsUpDoc#6_May_2016
 

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