To start that off, I am doing what I can to improve the roadmap page, just finished pushing out the communications plan parts that I can commit to, and have started a discussion on the mailing list about the roadmap and comms plan.

What I want to drive toward next (and very soon!) is a release schedule. I really do want to chop down and pulp up some trees (or use all post-consumer grey paper) to put out some actual handbooks you can hold. But that requires more of the content to just be there. (I don’t really want to print with any ‘example needed‘ sections.)

That git repository is now available on Fedora Hosted:

https://fedorahosted.org/tosw/browser

You can follow our guidelines on how to get the source and how to build it, or if you want to contribute you can use this to-do list:

• Start by joining and talking on the mailing list.
• You need a Fedora account (FAS).
• Read Contributing to The Open Source Way and Converting to DocBook XML.
• Read Using git repository for detailed information.
• To get commit access, start by talking on list and submitting patches.

Short-cut available. If any existing committer knows you and your work, that committer can sponsor you immediately for a wiki account and access to the git repository.

On an unrelated point, I was finally able to build a favicon.ico from the SVG I got from Josh Gajownik, Red Hat stellar brand design lead.  Along with the clean site design, we finally have a look for The Open Source Way that I can hopefully translate to a Publican brand package.  We also seem to have a universal preference for two important acronyms:

• tosw – the open source way — lowercase usage refers to the community-defined methodology.
• TOSW – The Open Source Way — uppercase usage refers to the community-created book (wiki + rendered builds.)

Thus, keep your eyes out for the `publican-TOSW` package I’ll be working on.

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://www.TheOpenSourceWay.org/wiki (read and participate)

http://www.TheOpenSourceWay.org/book (HTML, HTML single page, PDF)

This is a handbook for creating and nurturing communities of contributors.  It was originally thought of as a cookbook to provide recipes for enacting community the open source way.  It is released under the Creative Commons BY SA 3.0 Unported free/libre/open content license.

We originally wrote this handbook for internal-to-Red Hat use.  Our community team tells many of the same stories and makes the same points to different audiences, and we thought a handbook or cookbook would be a handy way to practice our own methods.

No surprise, it was immediately clear to us that this type of content is better if it draws from and benefits a wider community.  In this case, the community of practice of people interested in contributor communities.  That community writes this kind of documentation for itself.

As a source for repeatable and successful recipes, the book follows a simple format:

• First is a principle, explained in a paragraph.
• Second are implementation details, in one or two paragraphs.
• Third is an example demonstrating the principle in an implementation, in or two paragraphs.

If you want to use the book, you can start referring to the wiki pages immediately.

It has a nice PDF version, which currently prints to 30 pages (double-sided.)  This one is Red Hat branded, but you can take the DocBook XML sources and build it using whatever look you want.

It is also incomplete, specifically in the area of examples.  I don’t want this to be full of only technology examples.  That’s one place you can come in.  Give up some examples of the principles in action, from the real world, and ideally in realms outside of technology.

But it’s more than time to have this content out in the open.  Release early, release often.

After all, the open source way can be practiced in many more parts of life than just technology.

One final note.  What we refer to as the open source way is a rebranding of what are really techniques utilized in creating freed software a.k.a. free/libre software.  The brand of open source has a lot of recognition and traction with people entirely new to the discussion, looking how to apply these concepts in their communities.  When practiced properly, open source software is good enough as free software.  That’s how we do it in the Fedora Project.  As an effort to spread information about how to use free and open community techniques, we are relying upon the current strong Open Source brand in helping to amplify the message.

One section I hope to add to The Open Source Way soon is a version of the article by Richard Fontana, “The free software way“, published on opensource.com.  My goal is to provide a new, canonical location that explains the right way for free and open to interact.

(Update – first both links to HTML book fixed.)

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.

1. Rip out whatever logic you have in ~/.bashrc for displaying the git branch at your command prompt.
2. Copy the script supplied by the git package to where you can make it an executable, such as ~/bin :
   • cp /etc/bash_completion.d/git ~/bin/git-completion.sh
3. Make the script executable :
   • chmod 700 ~/bin/git-completion.sh
4. Add these two lines to ~/.bashrc :
   • source ~/bin/git-completion.sh
   • export PS1=”[\u@\h \W"'$(__git_ps1 " (%s)")'"]\$ “
5. Reload your bashrc file :
   • . ~/bashrc

Enjoy having a peek at where you are in your git directory:

[kwade@calliope lookatgit (debug)]$ git branch
* debug
  help
  master
[kwade@calliope lookatgit (debug)]$

First, I’m sure the intention was well-meant.  Thanks for trying to uplift open source technical writers.

Second, I put in a comment response on the blog entry, which was more self-serving than helpful:

Not sure what the metrics used are … but it is worth mentioning the group of writers at the Fedora Project. In terms of sheer number of pages and breadth of content, this is the upstream for all Red Hat product manuals:

http://docs.fedoraproject.org

Probably more than a thousand pages of CC BY SA 3.0 Unported licensed content.

http://fedoraproject.org/wiki/Docs_Project

Third, I really want to say — all this rockstar stuff is plain wrong.

It doesn’t inspire people and get them fired-up to get on the next top-ten list.

It drags down morale.

It is even a harder hit wherever there is a cross of passion and volunteer time.

Ask an artist if they love seeing a list of top artists in their region or media?  Unless they are on that list, I’m sure the answer is unpublishable in this family friendly magazine.

Call out group efforts and thank all those involved in no particular order and without leaving anyone off the list?  OK, that works.

But tweets to your homeboys when they do something you love in your community just makes all the people even peripherally involved in that effort feel left out.  Forgotten.  As if they don’t belong.

I’ve been wanting to say this for a long time.  I think it’s a basic idea that many Fedorans agree with.  But I didn’t want to be mean to fellow community leaders with good intentions who don’t realize their basic idea is off mark.

So, DMN Communications poster, please don’t feel singled out.  I am motivated to write this because I feel personally saddened that all the hard working writers who work through the Fedora Project are going to feel a bit marginalized from that top-ten list.  Ironically, isn’t the marginalization of open source writers in general the very reason you wrote the list in the first place?

Let’s not replicate the top-ten lists of late night TV and technical publishing.  We aren’t in competition with each other for popularity, OK?

(Updated to say “thank all those involved in no particular order”, with the “no” added; it was intended to be there, blame my editor.)