Improving the content of OpenStack wiki

The pages on wiki.openstack.org have been growing at a fast pace and it’s  time to give the wiki more shape: new contributors, end users and operators are having a hard time finding documentation since over time it spreads across many places. The wiki can have a role at directing readers where most appropriate. Luckily we have a team ready to help give the ~350 pages a more solid navigation and fixing content while at it:

  • Katherine Cranford (a trained taxonomist) volunteered to get through the wiki pages and propose a taxonomy for the wiki.
  • Shari Mahrdt, a recent hire by the Foundation, has volunteered a few hours per week to implement the taxonomy in the wiki pages, setup templates and write documentation to maintain the wiki.
  • I am overseeing the implementation and looking more carefully at content for contributors.

We are keeping track of things to do on the etherpad: Action_Items_OpenStack_Wiki. Shari and I started implementing Katherine’s proposed taxonomy: it’s visible as a navigable tree on https://wiki.openstack.org/wiki/Category:Home.

As an example of how the taxonomy works, let’s look at the tree of OpenStack Programs. One can think of Programs as teams of people using tools (code repository, bug tracker, etc) and coordinated processes to deliver one or more project to achieve a clearly stated objective. For  example, the Telemetry Program has a team of core reviewers responsible to drive development in code repositories for the Ceilometer project and the Ceilometer client, and each has pages for blueprints and specs, meeting notes and more. Programs contain projects, so the tree of categories under Programs will look like:
  • Programs
    • Telemetry
      • Ceilometer
        • Client
        • Blueprint
    • Block Storage
      • Cinder
        • Client
        • Blueprints
    • Compute
      • Nova
        • Client
        • Blueprints

You can see this live on the wiki on https://wiki.openstack.org/wiki/Category:Programs. Fairly straightforward except that over the years some of the pages have started with describing a project and have now been repurposed to illustrate a Program. Look at Nova page for example: the name of the page is “Nova” but the title is OpenStack Compute. We’ll definitely have to shuffle content around.  For example, the Category:Programs page can be considered a duplicate of the wiki https://wiki.openstack.org/wiki/Programs page: since everything on mediawiki is a page, the Category pages can be edited and can be redirected to/from like all other pages. In this case, it would make sense to make high level content like Programs more of a dynamic page, like Category:Programs. The cool thing of this approach is that we can probably create new category page for new programs automatically when modifications to the programs.yaml are approved via jenkins.

Adding a taxonomy and templates (more on this later) will help newcomers discover relevant content and find information more easily. While we implement the changes to the wiki we’ll also be reviewing the content on the pages, delete or mark as obsolete the old stuff and make things more readable for all. You can keep up with the progress by looking at RecentChanges.

If you’d like to help us out or find out more please feel free to contact stefano@openstack.org and shari@openstack.org

Only developers should file specifications and blueprints

If you try to solve a problem with the wrong tool you’re likely going to have a frustrating experience. OpenStack developers have been using the same workflow to plan and manage development of OpenStack software over time, they chose a set of tools appropriate for the project’s software development. Developers use blueprints define the roadmap for the various projects, the specifications attached to a blueprint are used to discuss the implementation details before code is submitted for review.

These are the tools for the developers and this doesn’t mean that blueprints and specifications are the only way to interact with developers. Operators and users in general don’t need to dive in the details of how OpenStack developers organize their work and definitely should never be asked to use tools designed for and by developers. When I read ‘s post the place of a non-developer in the openstack community I immediately felt her pain: she was asked to use the wrong tool to solve a problem. I think this case is a major misunderstanding but the comments on the post signal that this is not an isolated case.

The most common way for a non-developer to highlight a flaw in OpenStack is to file a new bug report. Bugs can be defects that need to be fixed  or they can be requests for enhancement. In this case, Dafna filed a bug report and interacting with the triager, they agreed that the reported bug was not a defect per se but more of a request for enhancement, a wishlist.

In order to fix a defect or implement a wishlist item, developers need to file a blueprint (and a specification) before they can start writing code. If the person who filed the original bug report is also a developer then s/he can go ahead and continue carrying on the process, file a blueprint to solve a bug # and write specifications (when needed) to describe the details of the implementation. Users interested in the bug can chime in adding comments to the bug and to the specs, provide input to developers.

The process above works in similar way when the person filing the bug is not a developer, like in Dafna’s case. The proper flow of bug #1323578 would have not required Dafna to file a blueprint and specs, but to have a developer do that. Users are required to interact closely with the developers to discuss the implementation details, and that’s where the new specifications process helps. Gerrit may not have the best UI but it’s definitely better than holding discussions on a mailing list. Adding comments and holding conversations with the developer assigned to resolve the issue, on the bug report itself is also a valid option.

While I think that as a community we have plenty of ways to improve how we include users and operators in our conversations, in this particular case, I think frustration came from being pulled in the wrong place from the beginning.

PS: To be super-clear, in this post I’m using the terms developer and operator to describe a role, not a person. One person can be at the same time a developer and an operator, and act at times as a developer writing blueprints, submitting code and as an operator filing bug, giving comments to specifications.

 

Shuttleworth sees Ubuntu as the universal OS

In his keynote this morning, Mark Shuttleworth sketched a future where by 2014 Ubuntu will be an universal platform on all devices with a screen. He mentioned Ubuntu-powered phones, TVs, tablets, cars, with the existing desktops and servers, all connected to the cloud. It’s a huge challenge.

I’ve been hearing this story of the universal operating system many times in the past 20 years and nobody has managed to come up with one. I’ve seen the failure of LiMo, Maemo and Meego later (not Tizen), WebOS and more in direct competition with iOS and Android on the mobile/embedded space. Mark may succeed where others have failed.