Just around a week ago we welcomed our second kid (and first son) into the family. Now we have one of each kind, and it’s undoubtedly going to be an interesting journey. As they say, having two kids is much more than twice the work, and most probably it is going to affect my open-source efforts in at least the short term. I’m doing this on my own free time, and the priorities in this matter are quite clear. But as you can see from the last three postings, the business is almost as usual, so don’t be too quick to run to the competition :)
Those of you who’re using the various libraries that i develop know that i mostly prefer the very liberal BSD license. This makes them very friendly to both open-source and commercial projects, and i’m quite thankful for all the feedback and bug reports that i get from the projects’ users.
I have added a new button to the project site. Clicking on this button will take you to our Amazon wish-list. If you want to express your thanks for one or more of these projects, support the ongoing efforts being put into them, and make sure that my wife views all the late hours in front of the laptop in a positive light, you’re more than welcome to click through.
As i was looking at the directions to a store on Google maps, i noticed that they’ve added a new functionality to click on each route turn point and see the “street view” shots. Here is how one of the exits off highway 87 looks on Google:
and if you manage to find your way through the parking lot, you’ll just need to drive through another house to get to Santa Teresa:
Reminds me of an episode in “The Office” where the boss drove the car into the lake a couple of yards before the bridge, just because the GPS lady told him to :)
Update: deciding to go a little bit further to Santa Teresa, Google would like you to go against the traffic:
and once you make it to the intersection, turn on red:
This is the final part of the series on one-man open source projects. In the previous entries i talked about the different facets of the issues that face single-developer projects:
There are a lot of big projects out there with dozens of active developers and hundreds of people actively involved behind the scenes. Sometimes, developers of these projects have the luxury to concentrate on what they love to do the most – coding. However, the terms such as steering committee, constitution, incubation and governance models do not apply to the vast majority of the open-source projects. Such projects frequently languish because their developers fail to recognize that all those menial and tedium tasks are crucial for the long term health of their projects.
Sometimes, the solo developer behind a fledgling open-source project has an unreasonably high level of expectations from the target user sector. This frequently leads to frustration from low number of downloads, lack of interest from the blogosphere and may even result in venting your anger against the competing projects in public forums, mailing lists and blog comments. While being the best in your field is an understandable goal, i would advise focusing on other aspects instead.
Is being the best a goal in itself? How about admitting the following three simple things:
- You know you’ll make mistakes
- You’re ready to learn from them
- You hope to not repeat the same mistakes in the future
This way, you will not be afraid to make a mistake, not be afraid to admit a mistake and be very quick to fix one. And in any case, what are your chances of being the best? Next time you attend a technical conference, look around you. What are your chances of being the smartest guy in the room? What are your chances of being the smartest guy at the conference? What are your chances of being the smartest developer using your favorite language? What are your chances of being the smartest guy in the world?
If you have a blog, if you have your own open-source project, even if you comment on somebody else’s blog – you want to be heard. If you’re open to comments, bug reports, enhancement requests and a genuine two-way conversation with your users, you will be surprised at how much you can learn from them. And if you have the ability to cut through the complexity, distill chaotic flows into a clean API and communicate without condescension, they will come.
P.S. This series was originally conceived as a session for this year’s JavaOne and OSCON conferences. Even though the reviewing committees were not overly impressed, i do feel that it is an important topic. You can download the full slides in PDF format. There are no absolutes. This is what works for me.
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:
