Today I was looking for a good manual on how to build correct and well-formed Debian distribution packages. As you might know, every package has some sort of description telling what application it holds, why user needs this application, what platform this application is supposed to work on etc. While it is a regular descriptor, it still plays big role in advertising your product.

From all these writings I learned several good lessons, which I would like to share (or discuss, if you wish) with you. Let’s start with thinking a bit about why we need the description.

We need the description for the product to let potential user learn more about it in order to decide to go or not to go with it. It’s quite obvious, you say, but we can see lots of applications having awful descriptions with exuberance of highly technical terms and odd language constructs. For me, as for potential user, it may be hard to understand all that, just because I’m not so clever as the author. So what we should concentrate on and how do we build readable descriptions to attract more users.

First of all, and it’s told everywhere, you should decide who is you target audience. For example, you can call very sophisticated email client as “powerful post-office suite” or you can tell “e-mail client with power features”. When user sees the terms he familiar with, he continues to read until the judgement is ready. When user hits the wall of complex or, what’s worth, unknown terms he stops to read and switches to the alternative.

Next, developers always forget which platform/environment/setup the product is intended for. Can I run it? You can list the prerequisites in any order, but the order of majority is best of all. This way, if you write the application for Gnome windowing system, you can tell “e-mail client for Gnome with lots of power features”. Looks simple and familiar? Yes, and it’s very easy to understand.

Now it’s time to describe why I, as a user, may need this particular application? What makes it stay apart from the crowd of all other alternatives? Let’s say your mail reader can handle very large mail bases and perform complex searches with multiple criteria quickly. You can’t tell this to user directly, but you can reorder words and simplify the phrase to gain more attention, like this: “It will help you to keep your mail boxes organized, no matter how large they are.” Now it becomes clear that application has tons of useful features to organize mail boxes in addition to classical e-mail client functions. And all of these features work lighting-fast.

To this point user usually has an answer on to go or not to go with your product, but he looks for some prove of his own thoughts. You can help him make the “correct” decision by dropping in some of your killer features in description. But don’t overload the text with details. Let the reader learn about 3-4 of them. Select them carefully and keep your voice simple. Say “The application can do this and this, it easily integrates with this service and makes this at no time.”. Two sentences are usually enough for this purpose.

If you wish to show your tongue to the other developers or just feel the need to emphasize some technical details or innovations, never put them in front of all. Carefully follow the selected path and build your description accordingly. Put your technical details at the very bottom of your description. Regular, not technically inclined user, should already receive all necessary information by these lines. Your details are mainly targeted on advanced readers. Remember that.

Finally, in the very end, place the bottom line with something, like this: “If you wish to learn more about the product, please visit us at ….”. It will guaranty that “hungry” readers will know the place where to feed themselves with enough information.

I hope that this writing will help you to create better descriptions for your creations. It can be a good start for your creative thinking. Just stop for a while and create your own strategy.