Fedora Summer Coding Evaluation

I am very grateful for having been allowed to participate in Fedora Summer Coding 2010.  I have learned so much about music and audio software, about documenting software, about the Fedora community, and about doing things in an open-source way.

One particular sore point has been bugging me throughout the entire process, and I want to get that out of the way first.  The original intention was to offer USD$5,000 to each successful student participant, but this was later reduced to USD$1,000.  The reduction was announced after the application deadline, but before releasing the results of which applications were approved.  I still don’t know whether I made the right financial decision this summer, and the late announcement of the reduction makes the Summer Coding SIG seem sneaky and unfair.  While the reduction was almost certainly done with the intention of allowing a greater number of student participants, it also undermines the legitimacy and viability of a Summer Coding program.  Had the original intention been to offer USD$1,000, I would not have applied – I would have gone on to seek a different job.  That said, it was my own decision to continue with Summer Coding after the smaller award was announced, and the $5,000 estimate was clearly marked as only an estimate.  The problem is that there is a large difference between the original estimate and the final result.

This was the only negative aspect of my Summer Coding experience.

The application process was a little bit confusing, but nothing that some careful attention couldn’t overcome.  Looking at the other applications, and the origin of those which were approved, it seems that non-native English speakers were at a significant disadvantage.  There were certainly other factors involved.  Many of the Chinese applicants, for example, wanted to work on the Ailurus package manager, which is not available in the standard Fedora repository, and replicates functionality in the existing PackageKit package manager.  Furthermore, I’m not sure that it’s a bad thing for the application process to be a little bit confusing.  If you’re going to be doing open-source development work, you must be able to work through LOTS of confusing documentation and instructions.  That’s the nature of the beast!  Even as I whine about this, the “Four Seasons of Code” Summer Coding project developed a repeatable, quasi-standardized application application for summer coding-like events.

Another thing about the application process is that it was quite demanding, and not all applicants finished all of the required components.  The only reason I was able to complete my project is because I took the application’s requests very seriously, and filled it out in detail that I thought was excruciating.  Success comes with planning.  Enough said.

After the application process, the Summer Coding requirements simply vanished, and I was basically left on my own (with my mentors) to construct a meaningful result.  It wouldn’t work for some people, buy my preferred way to learn and do things is independently for as long as possible.  It seems that “independently” is how many open-source projects get started.  Once an initial version exists, collaboration can truly begin.

Twice-weekly blogging is a pain, but invaluable.  Not only does it help to spread the word about your project, but you record some of your thought-process for you and other people to review later.  The next time somebody wants to write a user guide, they might check out my blog posts, for example.  In retrospect, I could/should have designed the blog posts much better, to illustrate the decisions I had to make, and why I chose what I did.  There’s always next time.

My mentors have been very helpful in sorting out problems with me.  I appreciate that they have not (generally) solved anything for me, but instead point me to the right source for information on how to do it myself.  One notable exception to this is when I set up the git repository, following my mentor’s instructions exactly.  This isn’t really useful for most people in most situations, however, and I probably won’t set up another git repository in my life.

The Documentation Project holds weekly meetings on IRC, and it has been helpful for me to attend these.  If there is a relevant project or SIG in Fedora, I encourage future Summer Coding participants to attend their meetings.  You will get to know people who can help you, and also learn about the workflow and efforts that go into producing a viable Linux distribution.  Be careful at meetings and on IRC though, because you never know who might be there… Paul Frields, for example, frequents the #fedora-docs channel and Docs Project meetings, but nobody warned me.  I only found out I’d been talking to the Fedora Project Leader well after the fact!


Summer Coding Final Report for Musicians’ Guide

The Fedora Musicians’ Guide is now complete (as required by Fedora Summer Coding, at least – draft is available at this link).  In case you’ve missed my previous posts, here’s a brief description of the project, how it began, and how it has developed so far.

The Fedora Musicians’ Guide (or “FMG”) was designed specifically as a Fedora Summer Coding project.  The idea came to me when I saw the request for student applications to Fedora Summer Coding.  Because I have taken two Computer Science courses, I thought I would try to apply for something.  When I looked at the existing proposals, I realized that two terms of CS just wouldn’t cut it.  After thinking about what I can do, I realized that, as a university music student, I have a rather unique view of Linux.  In particular, I knew that the existing documentation for music software was woefully insufficient.  It still is, by the way.  Thankfully, the Fedora community came together and allowed me to write a brand-new user guide for some of the most popular music and audio software available in Fedora (and some less-popular things, too).

The proposal was quite specific about the Guide’s goals.  The target audience is people like my friends and me, who study (or have studied) music to a relatively high level.  The document has relatively few technical musical explanations; users are expected to already know music notation before they use the LilyPond chapter, for example.  Users are expected to know what they want to do, but not how to do it.  In a way, I wrote the FMG specifically for my friends, because I was tired of saying “you can use this program on Linux,” knowing full well that a lack of documentation would prevent them from figuring it out.

The approach to each chapter shows the minimum skills required to use the application or program.  It’s best to learn through independent experience, so I wanted to explain as little as possible, encouraging readers to learn and experiment by themselves.  At the same time, I want to provide enough information that readers can guess intelligently how to do things.  This was very difficult, and I was always debating with myself about how much detail to include, and how much to assume the user would already know.

It was also important for me to write something distinctly different from pre-existing documentation.  Ardour and Audacity already have excellent user guides available on the internet, and SuperCollider has a very extensive collection of help files.  The point of the FMG, as much as it can be, is to get users started with the software as quickly as possible, showing them how to use it with follow-along tutorials.  The tutorials have instructions to create a particular, real-world project, with instructions for the tools being used, and explanations of why those tools are being used in that particular way.

The FMG currently covers the following software: Audacity, Ardour, Qtractor, Rosegarden, FluidSynth/Qsynth, SuperCollider, LilyPond, Frescobaldi, GNU Solfege.  There are also chapters about audio recording, computer audio, and real-time Linux systems, for users who need them.

It’s difficult to know how well the Musicians’ Guide has met the goals I set for it.  As development progressed, I found that it was much easier to write about the best software, and much more difficult to write about the merely high-quality software.  I fear that this shows in the resulting document – that software like Audacity (because it’s not new to me, and it crashed often) and Rosegarden (because it’s quirky and difficult to guess) are in the greatest need of good documentation, but that I was unable to provide it.

GNU Solfege, in particular, is a project that needs help.  I included it in the FMG because aural skills software is one area that computers are most useful to musicians, but it is always neglected.  The real problem is not that GNU Solfege is bad software, but that it simply needs more exercises.  These exercises are easy to write, too!  I sincerely hope that the Musicians’ Guide helps people to discover Solfege, and encourages them to write more exercises, especially for melodic and harmonic dictation.

Looking back over the whole project, there are a few things that stand out in my mind:
* Writing documentation is a tedious task, but a very useful one.
* Some of this software is *very* difficult to use by guessing.
* Some of this software seems difficult to use, but is actually easy.
* Most of this software is very useful, comprehensive, and high quality.

The point of Fedora Summer Coding (I think… ) is to encourage new contributors to the Fedora Project.  I am very grateful for the general friendliness and helpfulness of members of the Fedora community, and I feel like, even after just two months, the community has welcomed me as a valued part of the team.  I cannot emphasize enough how important it is to receive encouragement from other community members.  And it worked!  As it stands now, I plan to remain with the Documentation Project, helping where I can.

Musicians’ Guide First DocBook Draft Is Ready!

By the time you read this, the first DocBook draft of the Musicians’ Guide should be available on the Fedora Docs website, under the “Draft Documentation” heading.  The conversion from MediaWiki to DocBook did go much more quickly than I thought it would – very lucky!  Since then, I’ve also significantly overhauled a few chapters, have learned about the style I’m using, and have made several other small changes.

Over the next week, work will focus on these areas:

  • applying the style consistently across all chapters,
  • revising the text to make it as concise as possible (currently a problem),
  • incorporating comments from other testers.

The development deadline for Fedora Summer Coding is next Monday 9 August, and this last stretch is going to be a busy one.  Careful revision is a very slow, arduous process.  I usually end up writing a paragraph three or four times before leaving it.  This is the nature of writing, however, and I guess it parallels sofware testing, which usually takes five times longer than writing the code in the first place.

I’m really starting to understand why documentation is often left out of open-source projects, or left to become obsolete once it is written.