Skip to main content
 

8 tips for writing open source web apps that anyone can use

10 min read

I’ve spent my career writing open source web applications that are designed to be used by non-technical users. Elgg was a social networking platform that was described at the time as “MySpace in a box”. Known is a web platform that allows you to share and communicate from your own domain as easily as posting to Twitter or Facebook.

Elgg was ultimately used by organizations like Stanford, Harvard, Oxfam, Greenpeace and the World Bank. Known’s open source community is growing fast.

Here are some lessons I’ve learned from both projects.

1. It’s not about you

As a developer, it’s easy to approach software development as a way to “scratch your own itch”: building around your own needs and frustrations.

This is an important place to start, because it means you’re “dogfooding” the product: using it yourself, ideally every day. But it can’t be the only way you drive development, or even the most significant driver.

External feedback is one of the most important aspects of any software project. If you’re building software for a particular market, you need to talk to people in that market, show them prototypes, and react accordingly.

In a successful open source project, you’re getting feedback all the time, but it’s important to be aware that the people leaving issues and bug reports are a subset of your users. They’re the technically involved ones, who can manage GitHub (or wherever you host your project) and understand how to fill out a bug report. You can’t limit your feedback to the open source community, either.

When we were building Elgg, we regularly held meetups in pubs, in order to talk informally with the people who were using the product in the real world. With Known, we had the benefit of Matter’s accelerator program, which is heavily focused on design thinking. Over the first five months of our company’s existence, we spent over half the time talking to people, getting feedback on iterations of the product, and understanding their needs.

I’m convinced that good software development is a social process.

2. It’s not about the technology

Both Elgg and Known are based on PHP and MySQL.

Somewhere, a programmer is gasping. In the distance, a dog howls. A baby is crying.

One of the attributes of an open source project is that you can run it on your own infrastructure. That’s particularly true if you want it to be useable by less-technical users.

The web hosting landscape is dominated by shared hosts that allow you to upload files using FTP, install applications using cPanel and Softaculous, and pay $4 a month for the privilege. The people who buy these products in droves aren’t going to care to set up a Digital Ocean droplet or find an image in the AWS Marketplace.

It’s a strategic decision. If you want to use the in-vogue evented server platform, go right ahead. If you want distribution on the hundreds of millions of shared hosting accounts that non-technical people are using all over the web, then you’re going to need to meet those users where they’re at.

There’s also this: I’ve worked with PHP for years, and the language has never been better. In particular, PHP 5.4 has seen it turn a corner and become a modern web platform. So, at the very least, it’s not as bad as you think.

And you’re doing this to build a genuinely useful product, not because you just want to code, right? Right.

3. Design isn’t something you do at the end

Design encompasses the entirety of how your users will interact with your product. Yes, it’s the UI and the visuals, but it’s also the experience associated with everything from the initial installation, through using it day-to-day, to what happens if your users decide to move to another product.

See above: it’s not about you. Get as much feedback as you can. Watch people using your product; just stand behind them and take notes, and ask them questions at the end. Do this as often as you can. It can be heartbreaking, but it gets less heartbreaking over time.

Remember, too, that your product is open source. It’s okay if you’re not a designer. You’re almost certainly already thinking about how to involve engineers in your product development process. How can you attract and involve designers, too?

Confession: I don’t fully know the answer to this. On Elgg, we hired Pete Harris, a wonderful designer who defined the look and feel of the product. He didn’t know it, but he was the most highly-paid person in the company. On Known, my co-founder, Erin Richey, is a brilliant user experience designer. We’re very interested in attracting more designers to the open source community, but how this works is an open question.

4. Benevolent dictatorships are (mostly) A-OK

I’ve been a benevolent dictator in both open source communities. That means that I’ve had the final say about product direction and feature development. A lot of people believe that this isn’t appropriate in an open source community, but for this kind of user-facing product, I think it’s important. (Also, I’m a control freak.)

I believe that someone has to be able to say no on an arbitrary basis. A lot of projects and communities devolve into endless conversations, and sometimes argument, that hamper development. Being able to cut through this quickly is important - as long as you can act decisively!

All good products have an underlying vision that informs development. Someone needs to stick to their guns and be the keeper of that vision - while also engaging the community and being as open as possible to ideas, code and features. You’re a project leader, not a vanguard; keep an open mind.

5. Open is as open does

Your code needs to be super-readable and well-documented. Unlike most projects, lots of people are going to be reading it in order to understand your software. While some developers believe that you should be able to read the code, I think a documentation block above each class and method (at the very least) goes a long way.

Ideally, you need stand-alone documentation that can be read on its own terms. This is the equivalent of writing a book about your software at the same time as writing the software itself. Read The Docs is a great project that makes it easy to host searchable documentation.

Finally, you should keep the code as presentable and neat as possible. I’m not above using an automatic code beautifier to make sure that tabs, spaces, braces etc are all in line and standard throughout the codebase. If the source code is consistently formatted, it’s easier to read.

6. Your project is a community

Lead by example.

I favor lots of small source code commits over longer ones. Not only does that make it easier to roll back the source code incrementally, but it also lowers the barrier to entry for other people. If you’re committing a couple of lines here and a couple of lines there, it’s easier for someone else to follow suit.

It’s never okay to be a dick. There are open source project leaders who have become infamous for berating contributors for writing code they don’t like. That’s not only a great way to get a reputation for being an unpleasant human being, but also limit the kinds of people who contribute to your project. It hurts your software. Don’t do it.

Similarly, RTFM culture should never be tolerated. RTFM is a UNIX-era term for “Read The Fucking Manual”, which is how some communities interact with newcomers asking simple questions. That’s a horrible way for any community to act, and it limits growth.

Open source has a diversity problem. Being personally inclusive, watching for abuse, and protecting the culture of your community help you widen the gene pool of ideas. The greater the variety of people who contribute to your project, the stronger and more useable your project becomes.

7. Don’t over-integrate; don’t over-prepare

It’s easy to add a gazillion hooks into your software and prepare for any eventuality. I’ve seen projects spend months doing this legwork before producing something users can see.

Don’t do it.

Your project is already open by definition. It’s a great idea to add some hooks that allow other developers to build on top of your software. Both Elgg and Known have plugin APIs that have helped the projects grow healthy third-party ecosystems. But those APIs evolved over time, as a result of feedback.

The truth is, you don’t really know what’s going to be useful until the need arises. Real-world feedback is important. It’s a great idea for you to experiment and build your own extensions to the software, but remember that your platform isn’t set in stone: if you need a hook later on, you can create it. If someone in the community needs a hook that doesn’t exist, they can create it, or ask someone to make it for them.

It’s much more important to put your product in front of users and start getting feedback. Don’t spin your wheels on maybes.

8. Make it sustainable

If you’re doing something good for your users, you owe it to them to keep doing it.

Automattic, the company behind WordPress, is worth over a billion dollars. WordPress powers 23% of the web; there’s no way they would have reached this market share, or helped all those users, if they hadn’t been able to pay themselves to keep working on it. A flash-in-the-pan platform that hooks people in and then goes away is arguably harmful.

If you’re building a product for real-world users, you need to think about a funding model as a feature. And - sorry - donations are not a real funding model.

Known provides a fully-hosted service for people that don’t want to worry about the technical aspects of running a site. Our Known Pro product is an easy, turnkey solution for people who want to host their own professional website and reach their audiences across social media. We also have educational subscriptions, enterprise licenses, and organizational support.

From a business perspective, our open source product is a very cost-effective way to get wide distribution. It’s also core to our values: we believe that using open software is a core component of having control over your space online. That alignment between business and ideological considerations is at the heart of what we do.

Don’t shy away from making your open source project into a friendly, open business. You’ll reach more people, create a more useful product, and potentially change the world in the process.