Technology Foothold 101

I do a lot of new technology investigation and I can tell you that first impressions matter.
Far too often, my first few hours with a product consist of:

1. Trying to figure out what to download
2. Searching for simple examples
3. Fighting CLASSPATH and JAR file hell
4. Dealing with obscure “Name not found” types of exceptions

If my first day with a new product is miserable, I’ll probably move on to your competition.

Foothold 101

Here are some tips to make your product easier to approach and learn:

1. Ease the JAR file pain.
   • Reduce the number of JARs, if possible. Apache ActiveMQ lets you choose between a single big JAR or many small JARs. Having that single JAR is a blessing during early development.
   • Clearly list the requirements for each JAR. If your product ships with 30 JARs, provide a documentation page that tells us which ones we need, and why.
2. Provide 5-minute tutorials with simple example code. Many projects on The Codehaus have these 5-minute tutorials, and they are a fantastic idea. You can always follow up with more in-depth documentation, but the quick-start Hello World is — and always will be — essential.
3. Beware overly technical documentation. It is highly likely that new users are not experts in arcane P2P networking terminology. The JXTA project documentation is a really good example of what not to do. I struggled with this for an entire day and just gave up in utter frustration and rage, unable to get much of anything to work.
4. Your web site needs to be clean and easy to navigate. I am generally lost and confused when I try to navigate java.net projects like SwingLabs. Hell, their own search engine just crashed when I tried searching for “swingx”. I found it (and SwingLabs) through Google.
5. Make sure your damn demos work.
6. If your project requires me to compile, then let me type a single command to make it happen. I don’t care if it is Maven or Ant, just make it work. I’m here to learn about your API, not to diagnose a sloppy build.
7. Framework and API developers should spend a huge amount of effort providing useful error messages. There’s nothing worse than firing up a new product and seeing messages like:
   • Logging is not configured. To see output edit some magical XML file.
   • Name not bound. (Uh…where did you look?)
   • Batch update failed. (gee, I don’t suppose you could tell me a table or column name?)
8. Provide obvious downloads. If a particular release consists of three ZIP file choices, explain what those choices mean. Which do I want, and why? I generally just download all of them, because I’m afraid I’ll miss something. Check out the download counts for Guice. Notice that pretty much everybody who downloads guice-1.0-src.zip also downloads guice-1.0.zip. I’m not alone! Maybe all but the biggest projects should offer a single ZIP to download?
9. Make sure your ZIP file extracts to a subdirectory. Don’t you hate it when you unzip some new toy, only to find it just dumped everything into the current directory?
10. Provide an IDE-friendly ZIP or JAR containing all source code. This way I get proper JavaDoc tooltips and can easily navigate to source. Few things are more annoying that projects that ship with 15 separate parallel source trees, requiring me to spend precious time configuring a complex project.
11. Screencasts are a great way to get people started.
12. Concise documentation is often better than verbose documentation. Up-to-date documentation is priceless.

Credit

For the record, I stole the term “Foothold” from Mike.

This entry was posted on Thursday, November 29th, 2007 at 10:17 pm and is filed under Software Development, Technology. You can skip to the end and leave a response.