Jump to: navigation, search

Documentation/WhatsUpDoc

< Documentation
Revision as of 06:34, 26 June 2015 by Jaegerandi (talk | contribs) (Your suggestions for content)

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

Your suggestions for content

  • Add
  • Your
  • Content
  • Here

26 June 2015

Hi everyone,

First of all, our M release has been named! Sadly, it hasn't cleared legal yet, so we can't publicly announce it, however, here are the poll results: http://civs.cs.cornell.edu/cgi-bin/results.pl?id=E_4983776e190c8dbc It was a close-run contest!

This week, I've been continuing to dust off some old bugs, and have been chatting to a few of our docs liaisons to work out how we can best get them engaged with what we're working on. I've also been spending a lot of time on standards questions, and thinking about the future of the DocImpact flag.

Progress towards Liberty

  • 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 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
    • No progress this week
  • 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
    • Thanks to Yusuke-san for closing bug 1330005!

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:

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.

Docs Tools

Andreas and Nick just released openstack-docs-tools 0.29.1, after we discovered an RST translation bug in 0.29. Thanks for the quick turnaround on that!

Documentation Standards

There's been quite a lot of conversation this week over capitalisation of service names, with the community divided down the middle as to which we prefer! While we all enjoy a good style discussion, I've also asked Anne (in her role on the TC) to confirm the legal restrictions for us. Watch this space! In the meantime, continue to discuss this on the mailing list :)

Docs Liaisons

Don't forget that we have subject matter experts to help you with documentation questions that you might have. One of the best ways to get our liaisons' attention is to add them to a bug or a patch. Feel free to look up the liaison for the project you're working with, and add them to the cc list for your patch:

https://wiki.openstack.org/wiki/CrossProjectLiaisons#Documentation

Doc team meeting

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

Next meetings are: US: Wednesday 1 July, 14:00:00 UTC (note that this has NOT changed with daylight savings time) APAC: Wednesday 8 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

Of the three bugs we spotlighted last week, one of them was closed (thanks Yusuke-san!), and the other two are still up for grabs. Olga is working on a Spotlight bug from last week, too. Let's keep the momentum, with another three sad old bugs that could use some love:

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

--

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

19 June 2015

Hi everyone,

This week, I've been working on helping out the Ironic team to sort out their Install Guide (thanks have to go to Gauvain and Nick, who have offered to help out with writing assistance here), and trying to come up with some better ways to work with the i18n team, and our docs liaisons. More on all of that further in.

Progress towards Liberty

  • 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
    • We now have a team starting to form to work on Ironic docs. Contact me if you want to know more, or are willing to help out.
  • Improve how we communicate with and support our corporate contributors
    • No progress this week
  • Improve communication with Docs Liaisons
    • I have now reached out to liaisons. More later in this newsletter.
  • Clearing out old bugs
    • Thanks to Tom for closing bug 1195875. Let's keep up the great work!

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:

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.

Docs Tools

Andreas will shortly be updating openstack-docs-tools to 0.29.

Docs Liaisons

Don't forget that we have subject matter experts to help you with documentation questions that you might have. As you're working on bugs, feel free to give them a quick ping or an email to ask questions. They promise not to laugh at you!

https://wiki.openstack.org/wiki/CrossProjectLiaisons#Documentation

i18n Team

At Summit, I spent a lot of time with Ying Chun Guo (Daisy) from the translation team, to try and come up with a way we can make sure our teams are working together better. To that end, we've got a few ideas we're going to be implementing over the next few weeks. First of all, this newsletter now goes direct to the the translation mailing list, as well the dev and doc lists (hi translators!). Secondly, Daisy is going to poll her team to identify an i18n documentation liaison, who will be the go-to person for all questions about translation for docs. The other thing we're going to do is to make sure we're helping the i18n team to keep their status page up to date: https://wiki.openstack.org/wiki/I18nTeam/docs-translation#Document_categorize If you're working on a doc that is translated, please check that table and make sure the translation team know what you're up to! This will help prevent needless effort on their part, which benefits us all in the end.

Doc team meeting

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

Apologies for the timing confusion on that one, it seems as though daylight savings changes took us by surprise. For now, the meeting will remain at 1400UTC. If you would prefer it to be at a different time, bring it up on the mailing list, or in the next US meeting.

Next meetings are: APAC: Wednesday 24 June, 00:30:00 UTC US: Wednesday 1 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

Of the three bugs we spotlighted last week, one of them got marked as invalid (thanks Tom!), and another is in progress with SME assistance (thanks Olga!). That's great! Here's another three dusty old bugs that could use a polish up:

https://bugs.launchpad.net/openstack-manuals/+bug/1330005 Glance image properties and values (low hanging fruit)

https://bugs.launchpad.net/openstack-manuals/+bug/1394397 Nova notification_driver

https://bugs.launchpad.net/openstack-manuals/+bug/1205402 iPXE ISO boot support

--

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

12 June 2015

Hi everyone,

This week, I've been spending some time in the dustier corners of our bug list. Do you know we currently have over 500 bugs open?! Scroll down to the bottom of this newsletter for more on what we're going to do about that.

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

Progress towards Liberty

  • RST conversion:
  • User Guides information architecture overhaul
    • Waiting on the RST conversion of the Cloud Admin Guide to be complete
  • Greater focus on helping out devs with docs in their repo
    • Discussion with the Ironic team was started this week. We need a Speciality Team to take on this work.
  • Improve how we communicate with and support our corporate contributors
    • No progress this week
  • Improve communication with Docs Liaisons
  • Clearing out old bugs
    • I went through and pruned a lot of two- and three-year old bugs from the list. Please review and re open any you think still require tracking.
    • As part of this effort, I will be picking out a few old bugs to be spotlighted in each newsletter. Please take a look as they come up and see what you can do to help!

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:

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.

RST Common Files

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

Bug triaging

This week, the core team have noticed a lot of patches that have had to be cancelled, because they were fixing untriaged bugs. If you want to work on a bug, be sure that a core reviewer has triaged it before you create a patch. This will stop you spending time on patches that might not get accepted. We should now have core team available in most timezones, so if you need a bug looked at so you can get started quickly, ping the docs IRC channel, and a core should be around to help you out.

Doc team meeting

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

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

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

Spotlight bugs for this week

This is a way of trying to get some eyeballs on old bugs, in an attempt to pay down some of our technical debt. Kudos to Tom Fifield who helped me work out what to do about them! Each week, I'll spotlight a few old bugs here for people to go and look at and determine if they're still valid or not. Please check out these bugs, let's have a conversation (in the bug comments), and if you can close them, do so! To make this slightly more exciting, I'll be attempting to keep track of who is closing these old bugs, and will see if I can't put together a little care package to send the way of anyone who makes a real difference here.

https://bugs.launchpad.net/openstack-manuals/+bug/1195875 Controller Callbacks

https://bugs.launchpad.net/openstack-manuals/+bug/1201978 Pluggable Remote User

https://bugs.launchpad.net/openstack-manuals/+bug/1204566 Stop and delete operations


Keep on doc'ing!

Lana

5 June 2015

Hi everyone,

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

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

Progress towards Liberty

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

Kilo Branching

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

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

RST Migration

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


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

New Core Reviewer Process

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

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

Doc team meeting

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

Thanks Shilla for running the US team meeting!

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

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

Thanks! Lana


29 May 2015

Hi everyone,

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

Design Summit

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

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

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


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

RST Migration

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


New Core Reviewer Process

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

Doc team meeting

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

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

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

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

Thanks! Lana