All posts tagged ‘Open Source’

File Under: Programming, Social

Social Hosting, Good Parenting Are Keys to Open Source Success

It’s often said that you can’t kill an open source project.

The logic behind that maxim is that, as long as the source code is out there and freely available, someone will always show up to work on it, add to it, improve it. Indeed, that’s often the motivation behind releasing a project under an open source license.

One example is, the URL shortening service that shut down temporarily, but whose code is now open source. Another is OpenTape, a clone of the popular (and long gone) Muxtape music streaming app. Both released into the wild after the original developers became overwhelmed in the hopes that someone, anyone, would keep those projects alive. Whether or not the community actually forms around the release is irrelevant. The point is that it could.

But what do you do when an ostensibly open source project lacks support from its creators, and it becomes nearly impossible for the community to contribute? That’s the question programmer Jeff Atwood raised in a blog post Tuesday regarding John Gruber’s Markdown software.

Markdown is a text-to-HTML conversion tool which allows you to write web code using an easy-to-understand plain text format. Markdown text is then converted to structurally valid XHTML (or HTML). Markdown is used all over the web — it’s even understood by the content fields and comment forms within most popular blogging platforms, including WordPress and Movable Type. It’s been ported to Python, Ruby, PHP and other popular languages.

However, the original Perl script has remained largely unchanged since its release in 2004. In his post, Atwood takes Gruber to task for what Atwood calls “bad parenting,” an indictment of Markdown’s lack of bug fixes, updates and improvements.

Markdown was released under a BSD-style open source license, meaning the community can do pretty much whatever it likes with the code, so long as it respects the copyright notices and naming rules. Indeed, many ports of Markdown enjoy rather widespread support with numerous contributors and an aggregate community of active developers that the original Markdown lacks.

So while the various implementations of Markdown have regular fixes and updates, Gruber’s original code lacks such activity. What’s the difference? Atwood lays some of the blame at Gruber’s feet, citing what Atwood calls “passive-aggressive interaction with the community,” and quotes one of Gruber’s famously bristly e-mails (Gruber also writes the famously bristly blog, Daring Fireball) that shows the author discouraging changes. Single programmers rarely have that sort of influence. Which isn’t to say we disagree with Atwood’s assessment, just that Gruber is an extreme example and that it shouldn’t matter either way.

The bigger reason Markdown’s original Perl source doesn’t see bug fixes and maintenance releases seems to lie more its hosting situation than any other single problem Atwood raises. Without a way to easily contribute to your project, your potential users can’t improve your code.

The Perl source of Markdown is hosted as static download on Gruber’s website. Download the zip file and you’ve got a copy of Markdown you can use, modify and even redistribute according to the terms of the license.

But you don’t have a copy that’s easy to patch, and there’s no simple way to contribute back to the project, short of sending code directly to Gruber or to the support mailing list.

If the Markdown source code lived somewhere like GitHub, BitBucket, Google Code or any of the other free, open source code repository hosts, it would be infinitely easier for the community to contribute. To be fair, none of those sites existed when Markdown was released, but moving the code wouldn’t be hard — it’s a single archive with a license and readme text file.

A good project hosting service allows the community to contribute in ways that it just can’t when the code is static download.

Markdown isn’t alone in this respect. Django programmers were very excited to get their hands on the EveryBlock source code when it was finally released. However, since the EveryBlock code is, like Markdown, a static download, there isn’t and easy way for the community to contribute.

I have been using the EveryBlock code in a personal project for some time, and I’ve found at least a dozen bugs and several oversights and contradictions in the documentation. None of these stumbling blocks have stopped me from using the code, but it would be nice if I could contribute patches so others don’t also have to bang their heads against a wall for days on end trying to make the code work.

Yet a static hosting environment prevents that. There’s no easy way for me or anyone else to contribute to the code, update the documentation, add helpful links to a wiki, ask a question and get it answered. As a result, the whole community around the project suffers.

While it’s true I could put the codebase into a version control system and host my own copy, but not only does that feel wrong, it shouldn’t be necessary. The “you can always fork it” motto of open source has proved one of its least helpful tenets, leading to a proliferation of nearly identical code forks that are difficult to keep track of and work with.

We understand that the people who release open source code might not have time to work on it, or might simply lose interest in it over time, but that’s precisely why version control systems exist — to take the burden off the developer and let the contributions of the community pick up the slack in an open, organized manner.

Does a project still need an maintainer and someone to check in code, run tests, merge branches and so on? Sure, but that need not be a single person. Sizable open source projects — take Firefox for example — have dozens of committers and (in theory) no one person winds up feeling overwhelmed.

While in this particular case, it could be argued that Markdown doesn’t need further development. We use it everyday without issue. But the larger issue remains for other projects. Without active development, particularly bug fixes and maintenance releases, your open source project will rarely be successful.

Get your code into a decent version control system and make it easy for other users to do what you don’t have to — make your code better.

Photo by gerhard3/CC BY-NC-SA 2.0

See Also:

File Under: Programming, Software

Great Documentation Is Key to Open Source Success

Listen up open source developers, if you want your project to succeed you’re going to have to do more than write great code; you’re going to have to document it, teach new users how it works and provide real-world examples of what you can do with it.

That’s the message from Jacob Kaplan-Moss, one of the creators of Django, a very successful open source, Python-based web framework. At least some Django’s success can be attributed to its thorough documentation which is not just reference materials, but also includes tutorials, topical guides and even snippets of design philosophy.

Of course Django is not alone in having great documentation; Ruby on Rails is another highly successful open source project featuring great docs, tutorials and reference materials. Beginning to see a pattern? Great docs == happy, enthusiastic users == open source success.

Too often open source projects seem to turn up their nose at documentation, arguing that the code is well-commented or that developers should be able to figure it out for themselves — with the implicit suggestion that those who can’t don’t matter. That’s fine for some projects, but if you want your code to be more than a random page on Github, you’re going to need good documentation.

In an effort to help other projects improve their documentation, Kaplan-Moss has embarked on a series of articles outlining what he and the rest of Django’s developers have learned from the countless hours spent creating and refining Django’s docs.

While it’s worth reading through the entire series (and there’s more on the way), the basic message is quite simple: good documentation is more than just technical reference material.

What makes Django’s documentation stand out (and Ruby on Rails as well) is that it covers the details as well as the high-level overview of how the details fit together. Kaplan-Moss breaks down the types of documentation into three basic categories:

  • Tutorials — Tutorials are a great way to introduce users to your software and demonstrate high-level concepts in real world examples. Too many tutorials teach you little more than how to create a “hello world” script. Good tutorials should help your users actually build something, which is much more exciting for a new user than printing out a line or two of text. As Kaplan-Moss says “that rush of success as you work through a good tutorial will likely color your future opinions about the project.” Tutorials are the best way to make a great first impression on your potential converts.
  • Topical Guides — This is the real meat of good documentation and will be what users return to over and over again as they learn how to use your software. Kaplan-Moss’ advice is to aim for comprehensiveness: “the reader ought to come away from a close read feeling very comfortable with the topic in question… they should feel that they know the vast majority of the possible options, and more importantly they should understand how all the concepts fit together.”
  • Reference — Sadly reference materials are in fact what passes for documentation in much of the open source world. That’s not to demean reference guides; complete lists of class names and methods are absolutely necessary, but don’t stop there. As Kaplan-Moss writes, “think of guides and reference as partners: guides give you the ‘why,’ and reference gives you the ‘how.’”

If you’d like to see an example of well-done documentation that covers all these ideas, look no further than the Django Project website, which hosts all of Django’s documentation. The Ruby on Rails community has also produced excellent documentation.

Kaplan-Moss has two more parts to his documentation series, one in which he delves into topics like writing well, developing a clear, grammatically correct style and another that focuses on editing.

Kaplan-Moss’ post on technical style also covers things like markup and structural layout of documentation, since even the best documentation is useless if you can’t find what you need. For example one of the best parts of Django’s documentation is that every topic and reference page has a liberal dose of inline links that make it easy to jump from one section to another. While we wouldn’t suggest using wiki software, the everything-is-a-link model of wikis makes a good starting point for marking up your online documentation.

One of the biggest hurdles for many open source projects is finding good writers to create documentation. While Kaplan-Moss has some suggestions for making yourself a better writer, many developers don’t have the time to improve their writing skills. To that end we suggest paying close attention to your community.

Watch for blog posts from your users that offer tutorials or provide an in-depth at some aspect of your software. Contact the authors and see if you can incorporate their posts into the documentation. Give your users a chance to contribute not just code, but their understanding of the code — ask them to write more and make them a part of the project when appropriate.

Finally, perhaps the most important message of Kaplan-Moss’ post is that ultimately… some documentation always trumps no documentation.” Maybe your documentation isn’t on par with Django or Ruby on Rails, but don’t let that stop you from producing at least something. And be sure to check back with Kaplan-Moss’ site for more articles on creating good docs for your project.

See Also:

File Under: Programming

Ma.gnolia 2: Popular Bookmarking Site Opens Up Its Source Code

Magnolialogo_1Ma.gnolia, a social bookmarking service similar to Delicious, recently announced it will release its code as an open source project. Under the new plan, dubbed Ma.gnolia 2.0 or just M2, interested developers will be able to download the source code and incorporate it into their own sites.

The move is similar to what Reddit announced earlier this year with its “build your own Reddit” customization features and open source code base.

However, the Ma.gnolia announcement isn’t just about open-sourcing the code. According to a post on the company’s blog, Ma.gnolia also plans to rewrite much of its own site architecture.

M2 is a ground-up rewrite of Ma.gnolia, re-creating features we love today, taking a second run at what didn’t worked as well as planned, on a distributed, service-based architecture designed to handle the large volumes of data we’ve seen.

While Ma.gnolia is nowhere near as popular as, the site is notable for embracing open web technologies like OAuth, OpenID, APML and more. Ma.gnolia also offers some very nice features — like screenshots of bookmarked sites and cached copies of pages — that Delicious doesn’t.

Among the features planned for M2 are a new “stream” view, which will show you the latest bookmarks from your friends, support for both OAuth and OpenID, as well as some visual changes, like the ability customize the sidebar or theme the site.

Particularly noteworthy is the continued OAuth and OpenID support which means that, using the M2 source code, you should be able to build and host your own bookmarking site, but still use the OpenID login tools.

The code isn’t actually available just yet, but Ma.gnolia plans to release it to developers in September, and offer a public beta version of the new site by December.

See Also:

File Under: Mobile

Sync Your iPhone 2.0 for $99, Or For Free

Another major component of the iPhone announcement yesterday, in addition to the App Store I griped about previously, is MobileMe, the service previously known as .Mac.

For $99 per year, Apple will store all your data on their servers — email, calendar — and

auto-synchronize it to your desktop machine as well as your iPhone. It’ll all be accessible at too, when that site launches, on what will doubtless be a flashy Ajax-heavy page.

Apple says “ is such a great web experience, it seems as if you’re using desktop software,” and also “To use the new web applications, make sure you have one of these browsers: Safari 3, Internet Explorer 7, or Firefox 2 or later” — i.e., not IE 6.

Shortly after Apple’s announcement of MobileMe, I got a press release from Funambol, the open-source-happy mobile company, promising that their free sync software will do the same exact thing for free.

File Under: Software & Tools

Open Source Software Is Getting Better All The Time

Coverity ScanGood news for open source advocates: a recent study shows that not only is open source software reliable, the quality and security of open source software is getting better all the time.

The new study comes from Coverity, a long-time code analyzing company which has been running a statical analysis program known as Scan for the past two years. Scan looks at the source code of open source software projects to detect bugs and security flaws.

The Scan project is funded by the Department of Homeland Security, which wants to uncover (and fix) the most critical types of bugs found in open source software.

Coverity’s report, released May 20, shows that open source software is adept at rapidly patching bugs and even better, the overall number of bugs found has declined significantly in the last two years.

That means that not only are open-source developers creating high-quality new code, they’re also improving the existing code.

The report is based on 2 years of analysis of more than 55 million lines of code on a recurring basis, scanning over 250 popular open source projects like Linux, Apache, PHP, Perl, Python and other venerable names in the open source world. In that time some 8,500 individual defects have been corrected.

Although Coverity’s analysis isn’t going to detect every bug lurking in the dark corners of your favorite open source project, the survey does provide strong statistical evidence for the argument that code written by the community is every bit as secure and reliable as what you’ll find from proprietary vendors.

If you’d like more details on Coverity’s report, there’s a PDF available here.

[via OStatic]

See Also: