Jump to: navigation, search

Documentation/WhatsUpDoc

< Documentation
Revision as of 04:11, 27 May 2016 by Loquacity (talk | contribs) (27 May 2016)

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

Content Sources

Speciality team reports are gathered here: https://etherpad.openstack.org/p/Speciality_Team_Reports

  • Your
  • 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?

You can see older newsletters here: Documentation/WhatsUpDoc_Archive

27 May 2016

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.

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

Progress towards Newton

131 days to go!

Bugs closed so far: 107

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.

Speciality Team Reports

HA Guide: Bogdan Dobrelya No report this week.

Install Guide: Lana Brindley 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

Networking Guide: Edgar Magana We did not have meeting this week. Nothing to report. Next IRC meeting: Thursday June 2nd at 1600 UTC

Security Guide: Nathaniel Dillon No report this week.

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

Next meetings:

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

--

Keep on doc'ing!

Lana

https://wiki.openstack.org/wiki/Documentation/WhatsUpDoc#27_May_2016

20 May 2016

Hi everyone,

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? ;)

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.

Progress towards Newton

138 days to go!

Bugs closed so far: 89

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.

Speciality Team Reports

HA Guide: Bogdan Dobrelya No report this week.

Install Guide: Lana Brindley Meetings start up next week: http://eavesdrop.openstack.org/#Documentation_Install_Team_Meeting Cookie cutter has been merged, repo here: http://git.openstack.org/cgit/openstack/installguide-cookiecutter/ Need to merge spec: https://review.openstack.org/#/c/310588

Networking Guide: Edgar Magana We have successfully changedthe bi-weekly meeting schedule from odd to even weeks. There will not be meetingthis week. Next meeting will be on June 2nd.

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

Next meetings:

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

--

Keep on doc'ing!

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