If you write it they will come. Open source software has thousands of eyeballs monitoring it for flaws. Let the code speak for itself. The code is the best documentation. Haven’t we all heard this before, and haven’t we all had this type of wishful thinking? Alas, the harsh reality of hundreds of thousands of languishing open-source projects is in a stark contrast with the rosy promises and expectations that you might nourish when you start your own one-man open source project. Your pour countless hours into ??????developing and maintaining your project, only to see the weekly download count stuck at single digits, and community at large blissfully ignoring your labor. There is only one thing that you’re missing, and for some it might evoke an uneasy association with “those marketing suites”. In a one-man project, you are the developer and the maintainer, but you are also the tech pub, promoter, evangelist and marketer.

You need to stay passionate to continue developing your project even when nobody comes. You need to stay focused to maintain your project and properly prioritize different tasks. When it comes to promotion, you need to stay committed.

Most of the developers are introvert by nature, preferring to let the code speak for itself. The only problem is that there is too much code out there, and your potential users need to be gently and constantly reminded just how awesome your code is. Obviously, you’re not one of those “marketing suites”, and your target audience is your fellow developers. All you need to do is to think about how to “sell” your project to a guy just like yourself. That would mean highlighting the capabilities of your project, objectively comparing it to the competition (even when you’re lagging behind in some areas), not digressing into marketese and buzzword speak, and, perhaps most importantly, constantly staying on the radar.

The last part can be a turn-off for a coder. If you’re a coder, chances are that you don’t like to write documentation. Also, chances are that you don’t feel the need to discuss the reasons behind a specific design / implementation decision, especially if you’ve built yourself a little ivory tower. Chances are, even, that you don’t feel the need to create and maintain a comprehensive set of test applications that showcase all your awesome APIs. Finally, chances are that all you want to do all day long is to just write the damn code. Indeed, promoting a project takes a serious commitment, especially in the light of all the things that you need to do to grab peoples’ attention and don’t let go.

I have already mentioned this in the previous entry – new features should be the last item in your priority list, just after the documentation. I’ve also mentioned the catch-22 situation – nobody reads the documentation, but you must have it to answer the users’ questions in any case. It is your fault if the users need documentation to understand your library, and it is your fault if the documentation is too complex to immediately find an answer. However, the documentation is the “looks” that sell. Poor documentation or lack of thereof indicate a project that does not place enough value on users’ time. Documentation generated by Maven-like tools may fool the users a little, but the end result is an even more disgruntled user that was tricked into thinking there is documentation, when there is none.

Take a break from your frantic coding and ask yourself a simple question – how easy it is to understand your library for a user that has absolutely no knowledge in this specific area? Do you have a simple and intuitive index to guide the novice users around the basic concepts? Do you have a quick start guide? Is it kept in sync with your latest release / development version? Do you have simple examples that show how to use each single API method? Do you have in-depth tutorials for advanced users? You might be a star coder that can download a new library, load the sources in your text editor and start using it right away, but most of us are not. Do your project a favor and document every single thing that you can think of. And by the way, every time you get a question on “how do i do …” in a project forum or mailing list – it is your fault, even when it is documented.

Developers prefer to develop, especially when we are not confined by the project management to do all the tedium tasks. However, “the source code is the best documentation” is a sorry excuse, especially nearer the end of the release cycle. Instead of postponing the documentation until all the coding is done (which never happens), just spread it across the entire release cycle. You need to consider it as a vital part of the project tasks, and always think from the perspective of existing and potential users. Do not concentrate on how much you hate writing documentation. Instead, just do it.

The same principles apply to the test applications. While you should have a few big test applications that showcase your library as a whole, you should also write a very simple and complete example for each one of your public APIs. Keep them always in sync with the latest release (or the latest development version), interlink heavily and organize in an intuitive manner (grouping by business / related functionality).

Finally, have a blog. Get into the habit of writing 2-3 times a week. You might think that you don’t have anything valuable to say, but you will be surprised. If people want to download your code, they will also want to read your blog. It doesn’t have to be exclusively about your project. On the other hand, it doesn’t have to be about your favorite types of food. Once you get into the habit of writing, it will be much easier to continue doing so, even if English is not your native language. This might even come handy when you’ll need to write documentation at work. When everybody else is unhappy, you just cruise through and get to writing the code before they do.

There is a pleasant side effect when you blog about your project – from time to time you will get feedback from readers that are not users of your project. They might as well be potential users if you pique their interest, and they might provide very valuable feedback even when they have no intentions to be your users. You should never dismiss such feedback just because they are not your users. On the contrary, you might see why they do not intend to become your users, and gain some knowledge about your project, your goals and your vision.

The last entry summarizes the discussion.

The image is available under Creative Commons Attribution license from the following flickr.com stream:

• Ants on a rope by wwarby