My sense is that Publican is in good shape for groups to adopt and extend.¹  For example, there was a recent discussion in a MeeGo developer list about what tool to use for end-user help on the device console.  The first version of this help documentation for device users is going to be written using RoboHelp, a proprietary platform that has long been used for this type of capability.  (The thread does a good job of explaining the reasoning.  From my perspective, Intel and Nokia are showing thinking that is evolved and learned from the old days, such as when Red Hat Linux became RHEL and Fedora.  It shows they are learning how to use the open source way.  I’ve met and had discussions with various community facing folks from Intel and Nokia over the last few years, and they were listening and talking the open source way.  Interesting to see how others handle the experience.)

It seems like a good extension of Publican to handle this sort of help output, and if the MeeGo community coughs up a Perl hacker it can probably create the functionality relatively quickly.  Publican has been designed by the Red Hat Engineering Services team to support a need to deliver source documents + translated strings as multiple target outputs.  I’m sure it can be made to match the i18n requirements of the MeeGo documentation folks.  (I just learned that Publican has an EPUB output format, no reason it can’t be easily extended to a ‘help’ format.)

In the MeeGo thread, Dave Neary says,

Im (sic) my dream world, there would be a web application with a wiki-like interface, which would be a view to docbook sources, where changes were sent to a submission queue rather than being immediately displayed, where a maintainer could review and modify/reject/accept proposed changes, and anyone could view the review queue to see what the status for their proposed patch was. I don’t know of any such application

Dave, I think those components exist and only need a little bit of glue to work for you.  Publican plus an SCM on the back-end with Beacon running as a WebUI wysiwyg front-end.  In the summer of 2009 Satya wrote code that extended Beacon to support a subset of DocBook that the Fedora Docs Team identified as most used inline and block tags.  You plug Beacon in to a CMS as an editor to handle a writing/editing/l10n/publishing workflow.  (I think the CMS needs to handle the check-in/check-out with the SCM on the back-end, making the XML files available for edit, and probably adding a commit button in the chain so files can be saved as they are worked on without triggering a nonsense commit.)

We’re working on implementing Zikula in some CMS roles for Fedora, and I hope to see us adopting the Beacon editor there as a choice for writers.  This is going to be a whole new effort, and I’m waiting on the first Zikula instance, Fedora Insight, to be running before rallying more support via the SIG.

Where Wikipedia is a useful information source and starting place for deeper exploration beyond it’s reference-focused world, there is so much more that can be done with it to help teach the open source way.

In fact, you can teach all of the basics of joining a collaborative free and open source software community without ever getting more technical than how to get an account and edit a wiki page.

Here’s the process I would follow, in a US-based classroom.  You can adopt to fit in your environment.  This is applicable to all age levels – I’d encourage six-year-olds to define a good Summary log message and click the Save page button.  A good reference is the Wikipedia article on creating your first article.

1. Use Wikipedia as a tool for learning the open source way by extending your use as a research tool.  In other words, let the work be topic driven and associated with your other lessons.  For this procedure, consider the example of a class studying their local watershed.  When researching with the students, use Wikipedia as a resource to understand the larger elements of the topic, such as what a drainage basin is, how topology affects the local watershed, what hydrology is, and what are the laws about protecting watersheds and wetlands.
2. The first thing you can simply draw attention to is that the page for “Watershed” on Wikipedia is a disambiguation page.  It’s purpose is to guide you to other pages because the term you were looking for is ambiguous in usage, that is, it has multiple meanings that each have a separate Wikipedia article about them.  You can point out that this is a collaboratively done page.  Both the history page and the discussion page are rich with information about who wrote the page, when it was done, and snippets of why it was done.  (This is where a good guide to Wikipedia for participants is useful, to help the teacher learn more about what history and discussion pages, for example, are for, how they work, why they matter, etc.)
3. As you proceed through research using Wikipedia, look for and explain these items to the students:
   1. Red links – these are pages that do not exist yet, meaning there is information to link outward to from the article you are reading, but that Wikipedia page doesn’t exist yet.
   2. Mistakes, such as typos, spelling, and grammatical errors.
   3. Unclear or overly complicated writing.
4. The first contribution from the class is likely to come from finding and fixing mistakes or helping improve writing:
   1. When a mistake is spotted, do something about it right away.  Login as your user (read more below), note for the class that you are logged in with different links in the upper right corner, and click [edit].  Make the fix to the page, and when saving include a short but detailed Summary such as:  “Fixed spelling of a few words and corrected punctuation mistakes, all spotted by students in my 2010 6th grade science class at Branciforte Middle School, Santa Cruz, CA.”  When you save this message, it is logged with the edit and that information, which is retained forever.  Twenty years from now, your students can look up the work you did together on Wikipedia long after they have discarded the work they brought home from class.
   2. For helping to improve writing, you want to defer the committing of changes to the live page to the people who write and maintain the page regularly.  This is one of the purposes of the discussion page that each article in Wikipedia has.  Use that link and edit the resulting page.  For example, to add a new section to the [[Talk:Hydrology]] page, click on new section and fill out the form.  Give it a sensible subject, such as “Fix for confusing paragraph in the history section.”  In the body of the form include an explanation of the problem (why it is confusing), a fix (your rewritten-with-the-students’-help draft), and your signature (four-tilde characters ~~~~ are used to sign and datestamp automatically.) Save this new section. Main writers of the page will return and read your new section, comment on it or make the fix, and so forth.  When they are done with it, they likely move it to an archive page.  Check back with our students to see progress on your discussion topic.
5. Once a class has witnessed the power of editing a wiki, and had the pleasure of showing the change to friends and family, they are ready for the next level, which is creating a new page.  This is where the red links come in, which are put there by other authors of Wikipedia partially as reminders, and partially as an invitation to write the page yourself.  For example, the [[Hydrology]] page has a prominent red link at the top to [[water chemistry]].  Following that link gives you an empty page ready to fill.
   1. A good first goal is to create a nice stub page with a basic definition of the article topic, and a reference to back-up the definition.
   2. To be safe and sane, you’re going to actually build the initial page in [[User:Yourusername/Water chemistry]], then rename it to [[Water chemsitry]] when is is ready.
   3. Start by copying the structure, categories, and so forth from the page source of the [[Hydrology]] page, viewable together by clicking edit for the whole page.  Empty the content, rename sections, and make it a template ready to fill with information about water chemistry.
   4. Find out the markup to put in the page that notes it is a stub page, a draft, and needs references.
   5. This is an opportunity to show research beyond Wikipedia, since the original information sources must be found to use for populating and referring on the new Wikipedia page.
6. Once a new page (article) has been created, and shown widely, the class is ready for considering several new ways to participate:
   1. Continue to watch and work on the articles the class created as article maintainers.
   2. Write up a new Wikipedia article (more than a stub).  For example, if there are unique properties to your local, named watershed and no corresponding Wikipedia article, you may think it is notable and should have an article.  Divide the class into small groups and have them research and write each section of the new page.  References are important, etc.  Essentially, this is a written report but the report becomes a Wikipedia article.
   3. Define and work on a set of articles.  For example, your local watershed may be part of a larger watershed system in your state.  An entire class semester could be spent researching and writing a series of articles to cover the larger watershed system and the individual components of it.

Teachers need a Wikipedia account, with a user profile at [[wiki/User:Username]].  You can make all the changes in Wikipedia on behalf of your students to provide anonymity to individuals and put the aggregate class work under a single copyight holder. The profile should keep track of the general information about the class(es) the teacher has contributed from, such as “Alan Parsons Project Middle School 6th Grade Science”.  This is part of showing other Wikipedia people who you are and what you intend to do so that you have their support as you continue using Wikipedia as a lesson in the open source way.  It also helps create the record of the class’ work, for example, when students are applying to schools later and want to show the work they did.

This is a very short guide to this idea, really just a starting point.  I could see this being a longer document, including step-by-step for the teachers on joining and learning about how to contribute to Wikipedia.  Let me know if it helps, how it could be improved, or if there is another free content work covering this content I could support instead.  Or should it be a Wikipedia article …?

1. All the legal bits passed muster, and the new contribution policy explains the rules.  It’s simple enough – by contributing, you agree to put your contributions under the CC BY SA 3.0 Unported.  Read the policy for full understanding.
2. If you have a user account on the wiki, you are enabled to create new user accounts.  That is how we are going to allow in new contributors while keeping out spambots.  You are entrusted to make sure new people you add understand the contribution policy.

I’ve also started a big task list on the wiki, and am waiting for the new mailing list tosw@lists.fedorahosted.org to be created.  All part of following the directions:

• Set up a mailing list first
• Use lightweight, open collaboration tools – wikis, mailing lists, IRC, version control, bug trackers – and give out access
• Tasks, tasks, tasks or ‘Project management matters’

To get permissions to edit the wiki, I have put a human in the way (currently just me).  I’m working on getting up content on the user creation pages that explains how to request access.  I don’t like adding this barrier in an otherwise self-service process, but … default wiki configurations invite spambots, and we don’t have the resources to watch the wiki that way.  For the time being, we’ll have humans create accounts for other humans.

Maybe I can tweak the wiki permission structure so any normal user can create other user accounts?  That plus a detailed how-to page could go a way toward lowering the barrier a bit.  My goal isn’t to approve/disapprove people; anyone who asks and agrees to license under the CC BY SA 3.0 is welcome to participate.

It’s an ongoing situation, and that’s the difficult part of release early, release often.  If I waited until all these things were perfect before releasing, it would take even more months.  As it is, the content itself hasn’t been updated since September 2009.  That was because we got it to the point of being good enough to start working on externally, and it has taken the interim time to arrange and create the upstream hosting.  It’s rough around the edges, but improving every day, in part thanks to all of you finding and reporting problems.

The next goal is to move beyond the “file bugs and help test things” stage as quickly as possible.

http://en.wikipedia.org/wiki/Red_Hat#Programs_and_projects

It lists a number of projects that are not really in existence, and are arguably not any more worth calling out than other projects.

Take a look at that content and the section on utilities and tools, then compare it with this canonical page on the Fedora Project wiki:

http://fedoraproject.org/wiki/Red_Hat_contributions

In that comparison, realize something – both of those pages now share a content license.  The list of Red Hat contributions is licensed CC BY SA 3.0 Unported.  The same as the Wikipedia page.  (I’m asking about the GFDL question on fedora-legal-list.)

As a Red Hat employee I feel socially awkward rectifying this situation.  Is that incorrect?  I don’t know, I’m not a regular Wikipedia contributor and have lapsed my knowledge of what is right and proper in authoring an article.  Maybe it’s better or worse if the content is an aggregate from the Fedora Project wiki.

One idea would be to link to the canonical article from the Fedora Project.  That’s not bad.  But what about a new Wikipedia Red Hat contributions page?  (Or would that be [[Red Hat software contributions]]?)  I would envision the Wikipedia version to be a downstream usage, meaning someone would commit to maintaining it the way we maintain packages in Fedora.  For example, watch the page for changes, then carry those changes to the Wikipedia downstream page.

The value added on the Wikipedia side?  A properly categorized downstream page that re-sorts the content in to ways useful by the general Wikipedia audience.  There are probably other ways to enhance the content to be useful to Wikipedia, and still refer to the canonical upstream.

On the other hand, maybe one of you Wikipedians will tell me that it’s perfectly fine for me to write and maintain this page on Wikipedia myself.  In that case, maybe I’ll do it.  Otherwise, I’d be happy to help contribute, and I know of a few others who would likely do this already.

Or you’ll tell me it’s not appropriate for Wikipedia, in which case, I’d like to get the two sections I reference above to be removed from the [[Red Hat]] page.  They stand in stark contrast to the reality.

There are a small number of email threads you can catch up on, all of which are findable through this canonical thread on fedora-advisory-board.  I am writing this blog post as a canonical location for my arguments and reasoning, then I can refer to it endlessly.  (You know, canonically.) It may form the basis for a wiki page that represents a more formal Fedora stance, but for now, these are just my opinions, YMMV, IANAL, TINLA.

Here is the scope of what this relicensing covers:

• All content on the Fedora wiki
• All Fedora guides at docs.fedoraproject.org
• All upstream guides at fedorahosted.org, including the content sourced from Red Hat

Here’s the uncomfortable and most risky part:  to do this, we have to use clause 2(a) in the Contributors License Agreement that allows the Fedora Project to relicense (sublicense) contributions:

… a perpetual, non-exclusive, worldwide, fully paid-up, royalty free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute your Contribution and such derivative works; …

Why? Because it is vital that Fedora get off a content island and join the rest of the world.  Because the problem of gaining permission from every person who ever edited the Fedora wiki is a huge task, and it’s not necessary. This is why the current CLA has this clause, which should be understood by everyone who agreed to the CLA, but I expect people have different levels of understanding about how the Fedora CLA works.

I’ve been referring to this clause as the nuclear option, an expression that means, “The one option you keep available in case you ever need it while praying that you never ever ever need it.”  A bit dramatic, yes, but I think it reflects the feelings people have around the issue.  Folks just plain don’t like it when you go and relicense their work. At least we should explain why.

Why is it a really great idea to relicense Fedora content to the Creative Commons (CC) Attribution-Share Alike (BY SA) 3.0 unported license?

1. We are relicensing from the OPL (Open Publications License) 1.0.  The author and once-and-only-ever maintainer of the OPL wrote two years ago why people should stop using his license in favor of the CC licenses.  Please read that, it is well reasoned and makes compelling arguments, even more so because it is from the OPL’s author.  He wrote that two years ago, but quotes himself from 2003 when he recommended using a Creative Commons license instead.  ‘Nuff said.
2. Fedora’s legal advisors, specifically Richard Fontana, highly recommend a switch from the OPL to the CC BY SA.
3. We are on an island nearly alone with the OPL.  One of our main fellow inhabitants is Red Hat, who relicensed their content under the OPL without options so it could be used by the Fedora Project (and developed here, in advance of the next version of Red Hat Enterprise Linux.)  Since Red Hat is willing to change, we can move from a tiny archipelago to the largest continent of open content under the flag of the CC BY SA.
   1. Ironically, one reason Fedora switched from the GNU FDL to the OPL was the idea of being downstream of content from Red Hat’s professional writing team.
4. Other organizations that have content we can reuse in Fedora and contribute back to, such as Wikipedia and GNOME, have switched or are switching to the CC BY SA.  Why does this matter? For one easy example, we can write a definitive history of Fedora, host it on Wikipedia as the upstream, then package it as part of the ‘about-fedora’ package.
5. If you’ve never looked at how much open content there is on e.g. flickr.com and Wikicommons, please look.  For content authors, this is going from practically zero useful open media available to tens of millions of photographs, diagrams, and so forth that we can not only freely reuse, but we can contribute back to.
6. The formal content work of the Fedora Docs Team flows back and forth with the wiki.  It wouldn’t be possible to relicense just the DocBook-based guides, such as the Release Notes, Installation Guide, or Security Guide.  These all have content that may or did come from the wiki.  There is an interdependency that cannot be easily unwound, nor is there a reason to, as long as both the wiki and the guides are using compatible licensing.

To be honest, this change is probably a bit overdue.  Most of the time, though, you can’t push the river, it has to flow as fast as it can in the direction it wants.

Any thoughts about all of this?

(In this article I’ve been referring to the unported version of the CC BY SA 3.0 license.  At the time of this writing (20090707 ~0300 UTC), I have just asked for clarity on what Fedora’s position should be with regards to ported and unported CC licenses.  When this is clear, I will update this article to reflect. Updated based on Spot and Luis saying ‘unported’.)

2.25x the number of unique wiki editors are doing 4.7x the amount of work after the migration and training (9.4x total)

The graphic shows several very interesting facts:

• For seven months leading up to the migration to MediaWiki, there is a steady rise in unique wiki editors, but only a very low rise in the number of edits actually made.  More people making fewer edits per person.
• The first initial spike in edits is the import of data in to the new wiki, done using MediaWiki’s API (iirc) that tracks them as actual edits.
• After all the initial migration is done, there is another highly active month of edits in June 2008, including a significant amount of manual clean-up and re-organization.
• Then there is a drop-off in edits starting in July 2008, with one very low period in August of 2008.  After August, some of us form up a wiki SIG.  We improve the how-to documentation, hound people on how they work with the wiki to improve their experience, and in October 2008 form the fedora-wiki list.
• Things go along steadily until FUDCon 2009 in Boston in the first week of January.  At this conference, several things occur.  We work harder on teaching how to use the wiki, we talk up the page renaming , and we recruit several people to work on massive page renaming projects.
• The next rise in edits follows all the page renaming work, and results in a better organized, more usable wiki, month-after-month.
• All during the time from the migration to MediaWiki, the number of unique editors remains overall steady.  Comparing March 2008 (705 uniques) and March 2009 (973 uniques), almost the same number of unique editors are doing nearly seven times the work.  1,280 edits compared to 8,650.

One thing this all demonstrates for me is the power that one or a few individuals can have to positively affect the daily lives of thousands or millions.  This is why we put our energy in Fedora in to those contributors, because that lets them put their energy where it does the most good for the wider array of users.

The OSWALD (Oregon State Wireless Access Learning Device) is built from the ground-up from idea in the Summer of 2008 to the first units in first-year CS student hands on 23 April 2009.  It runs OSU’s version of an OpenEmbedded Linux; check out the full software stack to see there is a lot of capability in one hand.  It has ports for external devices (via USB) such as keyboard, mouse, monitor, and GPS.  The unit itself has a joystick with click for the left thumb, ABXY keys and a thumb-size touchpad plus buttons for the right hand.  It holds in your hands like a handheld game device.

It is also fairly raw, especially in terms of additional software ports, because it is a platform for students to learn on.  In his first-year CS class yesterday, Carlos Jensen handed out the devices for the first time.  The students’ first assignment is to write an MP3 player so they can listen to music on it.  Next week they work on the user interface for the player.

Ironically, the students who are doing the work to bring this to first-years are amongst the last class to work on dead-code autopsies. They were in the same first-year class long ago and no handheld like the OSWALD was in sight.

OK, so now the students have a handheld that encourages them to hack it for their own needs.  To provide the other half of the circle, OSU has a new social project hosting website.  They did a lot of work to blend Elgg and Trac into a seamless project tracker that makes friends want to flock.  Although they are running this as an OSU-specific project hosting with an open/public view, it can accomodate their industrial partnernships and class privacy needs.  They sound ready to roll this solution for other educational institutions to use, and I think they have a good chance for strong adoption.  I’ll be writing more about this, since I’m going to do what I can to help get it packaged for Fedora.  The concept is strong and the field seems pretty wide-open to get filled with a stellar open source solution.

We intend to show ourselves as another example of how a project can organize itself on the wiki, but we have a ton of crufty content to work through.  The work was done by Susan Lauber, who has been working with the Packaging Committee and Docs for some weeks on cleaning up both groups’ wiki presence, and John J. McDonough, a very active Docs contributor with a real clue how much better things can be in Docs.  Definitely Golden Shovel of Wiki Gardening Award time!

1. As you update the QA pages, please follow the wiki page naming and structural guidelines.
2. At least a few of you working in QA and maintaining wiki pages should join the fedora-wiki mailing list.  It’s a relatively low volume, high value list where we discuss wiki policy, tips, and so forth.
3. If you are going to be renaming some or all of your pages (and you should if they are in the unsearchable format of “Some/Content/Deeply/NestedWithCamelCase/Names”), then take a look at the wiki page renaming project.  If you have commit rights to anything on fedorahosted.org you can check-in and maintain a pipe-separated values (PSV) file.  Take a look at the existing ones for format.

If you’ve any questions about this or other best ways to work with MediaWiki, drop by #fedora-docs anytime and ask for guidance.  If you are fortunate, the Wiki Czar will be lurking.