an Open Letter to Fedora Maintainers

This post was originally drafted as a reply to a discussion on desktop@lists.fp.o about gaining marketshare.

GNOME Software is awesome. I started a fresh F22 installation on my laptop and thought I had installed.. $package. Whatever it was. I typed out the application name, a matching thing popped up, I pressed enter, and found out "Oh, this isn't installed, I need to press this one button first". Then I was done. It was really easy; no messing around with a terminal, no visiting sketchy blogs, no third party sites visited. I have a sense that this is exactly the kind of experience you'd like when a user wants to use flash, or Virtualbox, or listen to MP3s - everything they want to do Just Works on Fedora.

There's a problem with this. The user that's completely dissuaded by four lines of cut and paste instructions to make all that happen is going to gleefully appreciate that "Fedora Just Works with my flash videos, mp3s, and videos! I didn't have to do anything". We can sit down and discuss the technical, by the books compliance with stated policy by not shipping the bits, or metadata that provides the bits - hey, it's just a URL to the metadata, it doesn't load anything until the user initiates something. It's a tired discussion, and one that IMO continually misses the point. First, I hope nobody actually thinks that obfuscating this is different - to the end user - compared to actually shipping it. Why do people with nvidia cards appreciate Ubuntu? It offers them the nvidia driver. Not installs for them, detects and offers it. The user is making the choice there. We don't do that; the user has to open a browser, type "Fedora Nvidia", click several times, then perhaps cut and paste a line into a terminal. I have a lawnmower with more complicated instructions - and I can disassemble it and replace broken bits with spec parts if I need to.

More importantly, there's a compromise of the project's values. Not company policy, not bureaucratic red tape, not a few difficult community members that need to be convinced that the easy way is better. Core. Values. The compromise isn't decreased by making the user click "OK" or offering them a brief "this comes from a third party" to ignore. The licensing and patent issues that come under discussion are symptoms of a disease that, by consensus shown via participation, we all want to cure. The Fedora Project's highest goal is not to produce a competitive, easy to use operating system.

When someone asks me what makes Fedora different, especially a prospective contributor, I don't talk about how easy it is in GNOME to switch to an already-running application, or how nice it is that the gedit UI matches the UI of the system settings application. These are all good things, and they're all upstream and available in other distros too. I point them at Fedora's values, the project's commitment to furthering the Open Source Way, transparency, advocacy, staying close to open upstreams - all of the philosophy that results in a somewhat difficult transition from more tolerant platforms. The Fedora Project's Mission Statement, Foundations, and Objectives are required reading for contributors.

I'm shocked that these principles are continually treated as negotiable obstacles. Maybe some end up contributing to the project without thinking about these issues, or because their dayjob requires it, but many, myself included, chose a distribution to play in because of the community and it's principles. Kendell's situation is a great example; he's passionate about the ideology behind the project, and beginning to contribute because the project's values align with his own. He's written about the formats used for audiobooks made for the blind - DRM crippled, vendor lock-in at every level, really as inaccessible as an accessibility effort can be. You can understand his frustration when, after finding a project that's committed to advocating permissively licensed solutions to these problems, he finds that the developers responsible for the project's flagship product advocating abandoning those values for convenience and marketshare gain.

There are a lot of us out there contributing our free time in support of these values. I encourage everyone to do the same - if you strongly feel that patent and license restricted bits should be effortlessly available to end users, spend some free time improving a project like RPMFusion or Kokora. If you want to create a world where free culture is welcoming and widespread, collaboration is commonplace, and people control their content and devices, well, it isn't going to be that easy.


Cleaning up shortcuts with Powershell

I maintain a set of scripts for deploying Firefox ESR to my organization, as well as necessary internal CAs and an autoconfig bundle. During testing, a system was encountered that for some reason had residual shortcuts for Firefox 16.

These shortcuts, found in the user-specific start menu path, pointed at the old Firefox installer. User tries to launch Firefox, user sees a failed installation process. It's probably related to MSI deployment, which I've moved away from because a) I don't fully understand the mechanisms, and b) Mozilla provides .exe installers, not MSIs, and it's more comfortable not getting the binaries through a third party.

Shortcut Objects

Anyway, on to the code. It turns out that Powershell has a mechanism for object-izing shortcuts, making them quite simple to operate on.

> $link = ".\Mozilla Firefox.lnk"
> $shell = New-Object -COM WScript.Shell
> $shortcut = $shell.CreateShortcut($link)

Okay, now we have a shortcut object set up. Let's take a look at the properties of the object, and see what we can do with it.

> $shortcut

FullName         : i:\Mozilla Firefox.lnk
Arguments        :
Description      : Run Mozilla Firefox (Version
Hotkey           :
IconLocation     : C:\Windows\Installer\{3DF21514-3096-40DD-B6ED-E5B0256DAC32}\firefox.,0
RelativePath     :
TargetPath       : C:\Windows\Installer\{3DF21514-3096-40DD-B6ED-E5B0256DAC32}\firefox.
WindowStyle      : 1
WorkingDirectory : C:\Program Files\Mozilla Firefox\

Lots of options to play with here. We can change the icon, which currently is set to "The first icon embedded in the declared target" to something else by pointing to a file with embedded icons, and specifying the icon of choice:

$shortcut.IconLocation = "%SystemRoot%\system32\SHELL32.dll,14

Similarly, you can change the tooltip that appears when hovering over the shortcut:

$shortcut.Description = "Mozilla Firefox, YourOrg edition"

Operating on the other properties would work much the same way; give $shortcut.TargetPath a path, and so on.

Comparing Properties

Playing with icons and descriptions is fun, but in an unattended script, I want to be able to assess the properties and act accordingly. Conditionals with comparisons are simple, too:

if ( ($shortcut.FullName -like "\*firefox\*") -and ($shortcut.TargetPath -like "\*firefox\*") ) {
    # do stuff

Note that -like makes a sloppy match. It isn't case sensitive, even, just a basic string comparison. If you want to be precise, you have to actually build regex for it, and I'm not covering that here.

Seek and Destroy

In my case, I want to find any shortcut in any user's home directory that appears to be related to firefox, and points to the awkward Windows Installer path, and remove it. Here's what something like that might look like:

$shell = New-Object -COM
$FirefoxLinks = Get-Childitem -Path C:\Users -recurse -Filter "*firefox*link*"
$FirefoxLinks | ForEach-Object {
    $link = $_.FullName
    $shortcut = $shell.CreateShortcut($link)
    if ( $shortcut.TargetPath -like "*installer*" ) {
        rm $shortcut.FullName

Open Communities and Support

I wasn't a student of collaborative methodologies or a dedicated open source enthusiast when I began my relationship with Fedora. I wanted to learn to use the software, got help from the community, and wanted to return the favor. Some of you might remember those early efforts, and justly commend yourselves on your patience :)

In the intervening years, I've learned a lot more than I set out to. There's a culture in the Fedora community that's consistently offering a hand up, guiding towards better understanding, and iteratively improving for all.

Support Communities

Tech support has become a ubiquitous part of modern society. I think everyone's gone through the frustrating process of trying their best to make something work, giving in, and calling the toll-free number on the box for rote instructions.

In open source support venues such as #fedora, Ask Fedora, or various mailing lists, I found people offering assistance not out of obligation, but out of passion. There are no designated roles; sometimes you get help, sometimes you provide it. You might get very direct assistance, or discover a completely different approach to your problem that's much more effective.

People in Support

The most impressive aspect of this relationship to me is the attitude of the participants. Assertive or even coarse personalities accept and welcome correction of their statements, and discourse largely revolves around the merit of the ideas communicated. Because the conversations are accessible to all, everyone has the opportunity to benefit from answers to questions they've never thought to ask. I've gathered a lot of best-practices habits from reading mailing lists.

The take-home axiom from today's post is that the best way to learn is to teach - and the open nature of Fedora's support community not only proves it, but it affords us the opportunity to be taught while we teach, and about our teaching, and so on. These groups have grown their own continuous improvement mechanisms.

Enabling and onboarding users

To an open source project, a thriving support community offers more than just user satisfaction. It provides valuable feedback on the usability of your products, directly and by inference. With experienced contributors in the mix, contribution opportunities and community roles can be paired with individuals with particular skills. An IRC channel can serve as a recruiting station, simply by demonstrating the tenor of the community.

For a small project, this is easy; the developers communicate with each other over some medium, and make that communication channel available to their users. As a project grows, the development discussions begin to confuse or obscure the user questions, so another channel is used. This progression leads to the user channel serving itself, with expert users fielding questions from novices. The immediate user concerns are better served, but there's a loss of the tight sense of community that comes from talking directly with the developers.

How you think Fedora's user support lists and IRC channels can improve the user/developer feedback loop, and better catalyze new contributors? Comment and share!

Open Books

The Fedora Docs team is comprised of a small group of very talented professional technical writers, and a handful of community writers like myself. The group recently met [1] to discuss recent and upcoming changes in the distribution, revamp how we help new contributors get started, and take a close look at how we interact with the Fedora community.

The FAD was attended in person by a few folks meeting in Raleigh and a few in Brno, with others participating remotely from around the world. Besides discussing recruitment and training, we continued work on a new publishing backend that will eventually replace the terminally bloated web.git [2] currently in use.

the learning book

The Fedora Documentation Guide [3] received an overhaul. The book that once contained brief overviews of common docs tasks has now been expanded substantially. The Guide will soon feature a comprehensive introduction to DocBook, Publican, and git, based on Jared Smith's excellent presentations on the subject. The new and curious will be able to follow along with the guide using the "docs-beginner" [4] guide, a workbook corollary to the writing course.

In addition to the writers' training, the book has also grown a style section and an introduction to the community. We've found that new contributors can become too focused on the tooling and procedures; they get discouraged before writing much, or forget there are friends to help.

the cookbook

The complaint I hear most often from potential contributors ( besides the unfamiliar tooling & markup ) is that they don't know what to start writing about, or they have an idea for a short tutorial but don't know where to put it. The official guides [5] don't have a place for everything, and starting a new guide is a daunting task.

This is the primary problem I wanted to address at the FAD. We needed to find a way to help people write and publish short, autonomous articles. The solution had to be something approachable but still meet our high quality standards. It had to be something that would play nice with Transifex for translation. To be distributed, it needed static HTML with minimal maintenance requirements.

The answer we settled on is what will become the Fedora Cookbook [6], and it is a process as much as a book. Anyone can submit a 'recipe' for the Cookbook - currently to - using provided templates [7], and Docs volunteers will review, mark up, submit for translation, and publish. You're welcome to participate and learn as much or as little of that process as you like.

book in progress

To glue all this together, there's a mentorship [8] program inspired by Fedora Infrastructure's fi-apprentice program. There are some very knowledgeable folks to help with research, writing technique, markup, asynchronous bantering, whatever. Your mentor can walk you through the docs-beginners guide to a running start at the cookbook, or help with whatever you're interested in.

If you'd like to participate in the mentorship program or chat with the Docs team, stop in to #fedora-docs [9] during the newly instituted office hours. fedocal [10] will soon show blocks of time where we have committed to be available to the community.

The Docs team has been following along with, the different working groups, and the future of the distribution, of course. We haven't taken action, though; documentation is inherently reactive, and things haven't settled out enough to document.

During the FAD, we discussed our strategy for documenting Products and decided that waiting for the various working groups to define and request a documentation product wasn't the best approach. We have volunteers to track the product workgroups, and plans to compare notes regularly. I have volunteered to work with the Workstations group; the others will be introducing themselves soon if they haven't already.


immanetize blog!

the static site generator

After trying a number of FLOSS CMS projects, I've settled on Nikola [1]. It's simple to manage, easy to write for, supports translation ie Transifex [2], and static HTML means low server overhead and decreased attack surface.

Nikola is a very active project, with frequent releases for bugfixes and cool new features. I'm writing in ReStructuredText [3], familiar to most from GitHub by now, but there is support for a wide variety of source formats. Overall, I'm very happy with it so far, and there's a ton of features I haven't investigated yet.

the pushing of bits

To manage the content and the site template, git comes in to play (and let's be honest, I default to using git for everything at this point.) Nikola very nicely separates content from structure and presentation, so you can use separate repos; useful for a group that wants to have different permissions for each.

I've deployed the site to a vps [4] using ansible, including command-locked ssh keys to refresh content via cron jobs. Admittedly, that's probably overkill for a personal blog, but it's comforting to know that the effort required to deploy an updated site isn't much more than git merge production;git push --all. Migration to another VPS would be as simple as changing the target of a playbook and running it.

the composition of content

Content has always been the hard part for me. I can write howtos for procedures, like what's being used for this site (and you probably will see that howto, soon!) To publicly opine is a different story, though. As much as I appreciate constructive criticism, I've never been a big fan of unsolicited advice. As my community involvement has increased, however, I see the role of such things. There's a lot to be learned from the folks sharing on sites like Fedora Planet [5].

the ulterior motive

Put simply, search ranking. Not in the way you're thinking, though; I'm not after referral revenue or pride of place at the top of Google results. It's always bothered me to search for technical information only to find linkbait and outdated or even horribly ill-advised content.

It's become more than a pet peeve since joining Fedora Docs - our site's [6] search visibility is about that of an equatorial noontime shadow. If you're explicitly looking for it, you'll get results from there; if not, you'll find someone that tells you how to disable SELinux, set your vhost directory to 0777, or even obtain proprietary software from questionable sources. Yyeachk.

With some luck, my postings will give visibility to others' sites, that have quality solutions following solid best practices.

[1] A python static site generator:
[2] The translation platform used by Fedora, Fedora Docs:
[3] A simple plain text markup specification:
[4] My provider of choice just happens to be operated by a friend from Fedora:
[5] A site aggregating blogs from the Fedora community:
[6] Very comprehensive guides for Fedora: