Tag Archives: Opinion

SFProjectTools and WWW::SourceForge

In a bit of a change from the ordinary, I’m going to talk a little about one of my own SourceForge projects, the SFProjectTools project.

Every day, I look at numerous SourceForge projects, and this involved quite a bit of repetition. Looking up project descriptions, recent releases, contact information, and so on. As a long-time programmer, I strive to automate everything I possibly can, so that I can spend my time on things that matter, rather than on things that a computer can do for me.

As a result, I have a lot of scripts sitting around which perform many of the daily boring tasks for me.

The SFProjectTools project is an attempt to share the parts that may be of use to people other than myself.

There are, at the moment, three main parts to the SFProjectTools code repository. There are GreaseMonkey scripts, there’s a Perl implementation of the SourceForge data access API, and there’s a scripts directory containing things that actually use those Perl libraries.

The GreaseMonkey scripts provide various tweaks to pages on the SourceForge site which are particularly useful to me in my daily tasks, and which you might find useful. If you have your own GreaseMonkey scripts that you use on SourceForge, please contribute them.

WWW::SourceForge is a Perl implementation of the SourceForge data access API. It is distributed both here and on CPAN, and currently gives access to basic data about projects and users. More functionality is planned. I’d like to implement the entire API, of course, but I’d also like to implement the download stats API, which is full of very useful goodness.

The scripts directory, at the moment, contains just one script – event_influence.pl – which purports to measure the influence that a particular event (blog post, tweet, release, etc) had on downloads. It uses the API to count downloads in the N days before and after an event, and tells you what changed. This isn’t terribly scientific, but it gives you a rough idea if what you’re doing is working. I use this script every week to measure whether various promotional activities I did resulted in good things for the project. Of course, downloads aren’t the only measure of project health, but they’re a convenient and easy one to measure.

If you would like to participate in this project, please don’t hesitate to contact me.

Again, half as long

One of my favorite movies is “A River Runs Through It“, which tells a story of two brothers growing up in Montana. Their father, a preacher, conducts their schooling at home. In one scene, one of the boys is writing an essay, and each time he brings it to his father, his father tells him to do it again, and this time make it half as long.

I think of this quote often while trying to wrangle project descriptions into the miserly 140 characters that Twitter allows me. I want to tell each of you to rewrite your project summary, and this time make it half as long.

Here’s a few tips in shortening your project summary. (These are not absolute rules, of course – just suggestions you might consider in updating your project summary.) I’ve discussed this before, but I think it’s important enough to talk about again.

* Skip the “this project is an attempt to write software designed to …” bit. These are just extra words, and don’t convey anything about your software. Rather than saying that it’s designed to, or hopes to, or might some day, give me action words.

Before: “This project proposes to write software designed to edit audio recordings.”

After: “Edit audio recordings!”

Same meaning, but without the padding.

* Don’t tell me that it’s free and Open Source. This is SourceForge. Everything here is free, Open Source. It’s assumed. I always edit this part out when posting tweets.

Before: “This software is a free, Open Source podcast catcher.”

After: “Catch podcasts!”

Same meaning, but gets right to the point and doesn’t tell me something I already know.

* Skip words and phrases like “fast”, “easy to use”, “user-friendly”, “feature-rich”, and so on. You don’t have to tell me that your software is good. You have to tell me what it does, and then I can make that judgement on my own. Fast compared to what? Feature-rich? What features? Robust? As measured how? These things don’t add to my understanding of what your project does, and so just get in the way.

Before: This is a fast, robust, full-featured, user friendly birdsong identifier with a lovely blue user interface.

After: Identify birds by their songs!

Takes less time to get to the actual message, and tells me what I can do with it, rather than how happy I’ll be while doing it.

* I probably don’t care what language it’s written in. The “written in Java”, “written in PHP”, “written in objective C++” belongs in the detailed project description, not in the summary statement. I realize that this is a major selling point for some people, but it’s really not what your product *is*. I don’t care that my table was made with a Craftsman reciprocating saw, I care that it doesn’t collapse.

Before: Fast, robust full-featured wine database software, written in php with a mysql back-end.

After: Track your wine cellar on your website!

Tells me what it actually does. You can list your install requirements later.

As always, I’d be happy to advise you personally on how I would rewrite your project summary statement, if it were my project. Not that my answer is always the right one, but having read hundreds of project summaries, I know what catches my attention, and what makes me move on to the next project.

What does “success” mean?

When I first interviewed for the job of “Community Growth Hacker”, I was told that a major part of my job was helping SourceForge projects be “successful.” Naturally, I asked what “successful” means. I asked this of our CEO, and of my boss and co-workers, and got a number of different answers. I also asked the question of colleagues in Open Source, and got other answers there.

In the last few months, I’ve asked this question of people on a variety of SourceForge projects. I ask the question in many different ways, but I always ask it. The answers vary greatly.

This shouldn’t be too terribly surprising, of course. Open Source is driven by people who are volunteers – they’re working for a wide variety of different motivations, and not just for profit. So their definitions of success, too, will vary widely.

Some value fame (ie, popularity, large numbers of downloads, large user base). Others value utility – does the project do what I set out for it to do? To others, success means frequent releases, or quick time-to-close on tickets. And to others, success means happy customers or users. All of these are important, but which one the project admin values most will no doubt shape their attitude towards building their product and community.

This question was asked many years ago on Slashdot, and got a similarly diverse list of answers. And a research paper was written, largely based on the results of that question.

Frequent readers will no doubt note that two of the authors of the paper are also authors of the heartbeats paper I mentioned back in February, which is how I came across it.

I wonder if attitudes have changed at all in the 9 years since this paper was written. My experience is that they haven’t. People still do Open Source for an enormous variety of reasons – profit, fame, resume fodder, utility, boredom, interest in a particular topic, desire for community, altruism, and many others.

What do you think? Why do you work on Open Source? How do you know when your project is successful?

Translations

One great way to both attract new users to your project is by providing it in their language. The added ease of reading documentation and user interface elements in one’s own language takes a lot of the stress out of learning a new piece of software, and can quickly distinguish your product over others in the same space, even those with similar or even better features.

aPhasia

But, if you aren’t multilingual, how do you go about it? Well, it also appears that providing a mechanism for translation attracts new developers and contributors to your community, because it’s something that’s easy for people to do if they speak another language than the one in which the project was written.

As a citizen of the United States, I’m aware that I’m a part of a tiny percentage of the world who is not multi lingual. I used to live in Kenya, and the old joke went something like:

What do you call someone who speaks two languages? Bilingual.
What do you call someone who speaks three languages? Trilingual.
What do you call someone who speaks one language? American.

But most of the rest of the world speaks at least two, and usually more, languages. So translating a few user interface components, or a page of the documentation, isn’t a huge investment in time or effort, so it’s an easy way for someone to get involved in a project.

There are several resources for projects wishing to have translations done. By using one of these services, you can reduce the effort required for someone to contribute translations, without having to learn about your particular documentation format, your revision control system, or even know much about your product.

The Pootle project is a SourceForge project is a web-based translation tool. The tool itself is available in numerous languages, and the project website offers extensive resources about making your project translation-ready. The earlier in your project’s life you read this stuff, the more work you’ll save for yourself later.

virtaal-vista

Launchpad has a free service that coordinates translation for projects, and is used by a large number of projects, so has an interface that potential translators may already be familiar with. It’s easy to register your project there, but you’ll need to do some initial work to make your project translation-ready. Having text in the code, rather than in resource files, makes translation more complicated. Likewise, your documentation should be in formats that are portable between operating systems, and not tied to a particular application that someone might not have.

screen-shot-2012-03-02-at-115948-am1

DuoLingo looks like an interesting approach, but hasn’t yet launched, so I can’t really comment on how it works.

Get Localization was another service that was recommended to me, but which I haven’t used myself.

Guest blog: Programming Philosophies

[[ Today's guest blog was written by Nick Robertson from the AnsiGL project. AnsiGL is a modern "graphics" API for text-based applications.

The original article, as well as other thoughts by Nick, is over here.

I was particularly struck by point 2, as I've seen so many projects burn up hundreds of hours of time rewriting things that we're already well tested in production. We all have a desire to rewrite - it's part of the programmer mindset - but sometimes it's just a waste of time. Consider reusing libraries (like Boost, as mentioned in the article), or refactoring what you already have, rather than scrapping and rewriting from scratch. --Rich ]]

As I’ve been working on AnsiGL, there have been a few simple “rules” that I’ve been following I go along. Most of these things are probably old concepts to most of you, but hopefully these will help provide a little bit of insight for any up-and-coming programmers and for anyone who might contribute code to the project. I feel it’s important to share some of this not only for better understanding of the code in the project, but also to make sure that any potential developers can strive for the same basic goals. If nothing else, it might help answer why certain things were done the way they were done.

1. Let the compiler do it.

The single biggest rule that I have is one that anyone who has taken a programming course of any kind can tell you: KISS (Keep it simple, stupid). Anytime you can, let the compiler help you generate code. This is the biggest reason for settling with C++ (as opposed to C, for example) as well…for the reduced amount of code that I have to generate thanks to OOP and templates. Reliance on the compiler as an assistant programmer (sort of) essentially allows well-tested code to take the place of something I could otherwise screw up, while still allowing versatility. Not to mention, there’s much less code to test/debug.

2. Previously tested code is better than generating something from scratch.

I’ve also come to really appreciate things the Boost libraries…peer-reviewed code, pre-tested, and I don’t have to type it out myself to boot. Anytime there is another library that meets the requirements (without stepping too far outside the scope of the project…as was the case with most Unicode libraries I reviewed), it should be, at the very least, strongly considered for use in the project. There’s no need to solve problems over and over again unless the needs of the project dictate otherwise.

This “rule” has actually served a dual purpose for me. The above is relatively obvious…the second is that it really makes me think about a particular problem and what exactly needs to be solved. I end up reviewing multiple viable solutions in the process (ie, looking over other libraries that do what I need) and in many cases, I simplify my design. Sometimes the reason is because of interface demands and other times, I was simply thinking about a problem the wrong way.

3. Unit testing is your friend.

It may seem like lots of extra work (and it is), but the payout for the effort is rather large.

For those unfamiliar with the concept…a “unit test” is when a programmer isolates a single “unit” of code, and creates a program with the sole purpose of testing that “unit”s functionality.

AnsiGL is now full of examples of unit tests…even though they were written in haste and are buggy themselves sometimes. I decided to use each class as a “unit” for my purposes, so each class has its own test function. The sole purpose of that function is to test the class’s functionality…usually by manipulating the class by its member functions and verifying the results with expected (hard-coded) values.

This may all seem pointless since these tests don’t really amount to anything in the final product, but when adding new features and debugging, it’s absolutely priceless to be easily able to find what would otherwise possibly be intermittent or hard-to-find bugs. In short, I can essentially run this test application and it will tell me which functions are not performing as expected. This has reduced my overall development time a considerable amount.

Another benefit of creating these tests, is that you get to create your class interface in a somewhat “real” scenario. When designing an interface to your class, it’s rather important to know exactly how you need to use it, how you’d like to use it, and how it must be done…making a unit test forces you to think most of that out well before you make the time investment in lots of code that “doesn’t play well with others”.

4. Less is more.

If you can solve a problem with less code, that is typically the “correct” solution. Anytime I end up solving a complex problem, I almost always think of some way to improve it later on. If that “improvement” ends up being more code for roughly the same functionality, it is almost always the “wrong” answer simply because there is more code to maintain. There needs to be significant improvement (this varies from problem to problem) to justify complex code.

Something I’ve noticed in lots of code out there, is that programmers will program within certain paradigms, just because it’s slightly more efficient for the compiler (for example, ++var instead of var++ in a for loop). In my opinion, there are certain times it does make sense, but most often you should make it simple and easy until the code profiler tells you that it’s a bottleneck. Don’t program around compiler issues (unless it’s simple, like the above example) until it actually becomes a problem, because it can needlessly complicate code! Complicated code is a pain in the ass.