8 rules for documenting your product

This year I’ve had some really frustrating experience working with several new libraries and tools. In most cases, the reason for the frustration was related to the abysmal quality of the documentation for the products I've used. I do not want to point fingers and name the companies – from what I’ve seen, the problems I’ve encountered are not specific to these particular vendors, but, rather, plague the whole industry. Instead, I’ve tried to summarize my experience into some do’s and don’ts. So, if you want the user to have a good time working with your product…

1. Provide documentation in a well-known format. Make sure users can easily print all documentation, or selected parts. Avoid custom help browsers, exotic file formats and all this kind of garbage.
2. Provide all types of documents. Generally, a good set of documents should include Setup Guide, Manual, Reference and Examples. Each document here has its own purpose, and cannot be replaced with another. For some reason in many cases I’ve seen API reference provided as both Reference and Manual documents. Don’t do it. In the best case, user spends extra time trying to understand from the reference the right way to do something. In the worst, user has no other choice but to use Google.
3. Do not “crowdsource” your documentation. Forums, wikis, mailing lists, FAQs are wonderful, very useful tools – but they can’t replace a normal, “static” documentation.
4. Document all the relevant concepts. If the product introduces a new concept (algorithm, data structure etc.), it definitely should be described and explained as thorough as possible. If the concept is not new and is already used at least in some part of an industry, a reference should be placed to the available description and explanation. (Of course, a good judgment should be applied here. Definitely, there is no need to explain the idea of, say, mouse cursor. ) Specify all differences of your product with the existing standards.
5. Provide a 100% complete API reference. Even the trivial calls, like getters and setters should have descriptions. There reason for this rule is quite simple: it’s much easier to just document everything, than to try and correctly divide methods into trivial and non-trivial. Besides, pretty often a seemingly trivial method turns out to be much more complex than you initially thought.
6. Give each user access to all documentation. I’ve seen some companies allowing users to access only documentation for the products they purchased, and in my point of view it is absolutely ridiculous.
7. With each new release provide a “What’s new in this release” document, or at least a changelog. The document should not only highlight new features, but also specify most prominent bug fixes, and tell user about all cases when the new release is not backwards-compatible with the previous one.
8. Constantly maintain all dynamic online resources. Forum should be moderated and questions posed there should be answered, some popular questions should be added to FAQ, wiki should be cleaned etc.

Technorati tags: software, programming

R4DS and homebrew

Recently I’ve got my hands on a cool little add-on for Nintendo DS. It is called R4DS (Revolution for DS), and, basically, is a device which allows you to run DS homebrew applications from a standard MicroSD card. The device has a form factor of a standard DS game card, and acts as an adapter for MicroSD card. It has some sort of a shell software onboard, which allows you to easily access data on the flash card, to start programs etc. It is really an extremely cool gadget.

Well, it seems that Nintendo is not happy about the device at all. Nintendo spokesman is being quoted to say “We are keeping a close eye on the products and studying them. But we cannot smash all of them”. This, I think, in general summarizes the feelings of all closed-platform device producers towards homebrew.

On one hand, I can understand the reasons behind their position. R4DS and similar devices are being considered to be used mostly for game pirating – and, I have to admit, running “backup ROMs” is extremely easy with R4DS. So, the device seems to pose a threat to Nintendo and to all companies who officially develop games for DS.

But let’s look at this issue from a little bit different angle. DS is an amazing device, which is capable of many things (it has touchscreen, stereo sound, built-in WiFi), but currently locked almost exclusively to games. If you look at a homebrew directory, you will see a multitude of useful applications there – IM messengers, mediaplayers, email readers, communication tools - all written by enthusiasts. Just think – how all these applications would increase the appeal of DS to the customers, would they be officially accepted by Nintendo! Instead of alienating the enthusiast programmers crowd, Nintendo could help them, and, by doing this, simultaneously improve its public image and significantly increase their customer base. They could manufacture and sell devices like R4DS by themselves - another stream of revenue for them! Yes, the number of pirated game users will, probably, go up. But I strongly doubt that the change would be a significant one. After all, as all experience shows us, people who would run pirated games will do it this way or that, regardless of the existence of the official tools.

Situation with Nintendo is not unique. Generally speaking, homebrew scene for all platforms is always being frowned upon by the official platform producer. But I think that it’s time to change this attitude. Instead of fighting the enthusiasts, the manufacturers should join forces with them. This will lead to more and better software on better devices, which, in the end, is beneficial for all.

Technorati tags: nintendo, ds, r4ds, homebrew

Intellectual Property Protection Act of 2007

A new legislative proposal was introduced yesterday to U.S. Congress by Attorney General Alberto Gonzales. The new law, called “Intellectual Property Protection Act of 2007” not only increases penalties for copyright violations and makes it easier for the government to perform searches and seizures, but also includes something new: criminalizing “attempts” to violate copyright laws.

From the document:

“… an attempt to violate the criminal copyright statute should be counted an offence whether it is successful or not.”

I am not a lawyer, but this sounds scary. The document does not specify anywhere what constitutes an “attempt”. For example, imagine that I mistakenly configured my home web server so that my music collection became accessible from outside. No one ever downloaded anything – but it was an attempt, wasn’t it?

There is more interesting stuff in this proposal. For example, how do you like this one:

“…Because prosecutors work for public good, they should be able to institute an infringement prosecution even if the copyright has not yet been registered.”

Or this:

“…penalties that apply when the offense "consists of' reproduction or distribution, also apply when reproduction or distribution is intended but not completed.”

Or:

“Currently, a Federal court may issue an order authorizing the use of a voice intercept (otherwise known as a "wiretap") in the investigations of a host of Federal crimes; copyright and trademark counterfeiting crimes are not among them. This is unacceptable.”

You can read the whole text of the bill here (PDF), and some analysis here.

I do hope that this bill will never become a law. DMCA is bad enough without this sort of enhancements. Giving the government ability to sue people for attempts and intents to share a file is stupid and dangerous.

Technorati tags: copyright, law, DMCA

S.T.A.L.K.E.R - localization disaster.

Yesterday I’ve managed at last to get my hands on S.T.A.L.K.E.R. I was extremely interested in this game since the day it was announced (November 2001) for several reasons.
First, the game is loosely based on a sci-fi novel “The Roadside Picnic”, which is one of my favorite sci-fi novels of all the time. In Russia it was (and, probably, is) a cult novel, read by almost everyone. A masterpiece movie by Andrei Tarkovsky, also loosely based on this book, added to its popularity. (By the way, do yourself a favor and read it – not only will you treat yourself to one of the finest works of science fiction, but also, if you are playing S.T.A.L.K.E.R, you will get some insights on nature of the game world). The setting of the novel seemed to be amazingly well-suited for a computer game, and I dare say that it was a dream of many Russian programmers to create such a game. (I did one, very primitive, for a programmable calculator when I was in school). So, the news about a full-scale game based on the “Roadside Picnic” immediately caught my attention.

Second, I am very interested in the state of the game development market in Russia – partially because of my general interest in game design/development, partially because of myself being of Russian origin, and partially, because I am somewhat puzzled with the fact that Russian programmers, artists and game designers, having tremendous potential, still didn’t realize it in any significant number of world-class games.

And third… Well, as I said, the project was announced in November 2001. The original release date was sometime in 2003, but the game was delayed so many times that I thought the project eventually will be sacked to cut losses. So, when I’ve heard that the game is being released at last, I was all curios as to what is the result of the over-ambitious and over-delayed project.

Well, I am not going to write a game review here. It will be enough to say that the game is a resource hog, but is definitely worth playing. It looks beautiful, and it sounds…

Here we came right to the point I was going to talk about. It’s not the quality of the sound – it’s the fact that the sounds in the game were not localized at all. The game features a lot of speech – and in the version I’ve bought 3 days ago from a US retail store, all the speech is still Russian. (Well, to be more precise, all but the speech of some main characters.) It’s not only bad that the amazing ambiance effect is totally lost for non-Russian speaking players (I’ve spent 10 minutes just listening to a random conversations of non-player characters sitting around a campfire: they were discussing their lives, telling jokes and even playing a guitar! This is so cool – but 100% in Russian, without even subtitles). Some quite important phrases are left in Russian too. For example, if you approach certain characters with a gun in your hands, they will react by saying: “Uberi pushku!” which is Russian for “Put away your gun”. If you don’t understand this, too bad for you. Or, early in the game a helicopter appears above your head, and you can hear a radio conversation of military men in the ship, which goes something like the following:
-What’s this jerk doing down there? Let’s kill him.
-Let him be, he’s not that important to waste ammo on him…

And, as you could guess, the conversation is also in pure Russian, without any subtitles. So without knowing the language the player misses an important bit of information – the attitude of military towards him.

I feel really sorry for the developers and designers of S.T.A.L.K.E.R. It seems like someone was trying to cut some corners in localization. But as a result, not only the corners were cut – foreign players were also cut off the game. Such a stupidity!

Technorati tags: S.T.A.L.K.E.R., localization, gaming, games

Digg and the magic number

The story of the magic number which is claimed to be the HD-DVD production key is quite amusing. In short: the key somehow leaked, someone put it onto their blog and then published the story on Digg. The company which produced the key started sending cease and desist letters to all blogs that published this number. Digg got one of those letters, and the owners of Digg decided to comply and removed the article. This action infuriated Digg users - they started writing incredible number of comments containing the number, and the bloggers all around the world started writing posts about it. And, as a result, Digg owners gave in. Kevin Rose, the founder of Digg, put a post on his blog with the key number in the title, admitting that he heard the voice of the crowd, and that Digg will no longer remove the articles with the key. He said:

But now, after seeing hundreds of stories and reading thousands of comments, you’ve made it clear. You’d rather see Digg go down fighting than bow down to a bigger company. We hear you, and effective immediately we won’t delete stories or comments containing the code and will deal with whatever the consequences might be.
If we lose, then what the hell, at least we died trying.

The whole story in more detail is described, for example, here.

Just some of my thoughts on the topic:

• This is probably the first case which shows the real power of the sites with user-generated content; or, to be more precise, of the users of such sites. This case might become an important turning point in the relations between users and site owners.


• If the protection of HD-DVDs relies on a single number, then it’s in a sorry state indeed. I can’t believe that the developers of the protection thought the number will remain a mystery for any significant time.


• The behavior of the AACS (the company developing the protection and requesting the removal of the key from blogs) is an example of total stupidity. Frankly, they couldn’t do more to promote publishing of the key in thousands of blogs. This is similar to the story of Herostratus. One can think that by now people should learn: issuing a decree to forget Herostratus isn’t the best way to make people forget him.


• If someone needs another proof that DMCA went a little bit too far - here it is.

Technorati tags: HD-DVD, Digg, DMCA

Business rules: hard-coding or soft-coding

Couple of days ago “Worse Than Failure” published (instead of a usual daily IT horror story) a very interesting article dedicated to “Soft Coding”. The article discussed a problem known to anyone who ever did some business-related software design: dealing with business rules.

The problem with business rules is that they are almost impossible to generalize, often follow some odd logic and are subject to frequent and unpredictable changes. Usually business rules involve some arbitrary values, which programmers are reluctant to hard-code. The article gives quite a good example of the situation, but let me give here one of my own.

Let’s suppose that one of the business rules is:

“If a user account is inactive for more than 180 days it should be deleted, except for the cases when the user is located in New York or New Jersey, or when the user is an employee of XYZ Corp.”

The most straightforward way to implement the rule is just to write a couple lines of a code:

if (account.getInactiveTime() > 180 ) {
  if (   account.getUser().getState()!=”NY” 
      && account.getUser().getState()!=”NJ” 
      && account.getUser().getCompany()!=”XYZ”) {

     account.delete();
  }
}

The classic approach tells us that this code is bad: it has hard-coded values, which means that changing one of those values will require code change. The obvious solution is to move the values somewhere outside the source code, for example to a configuration file. But the logic of the rule itself is also subject to unexpected changes; so it will seem natural that the logic should be somehow generalized and the concrete details should also be moved out. Unfortunately, this almost always leads to creation of some monstrous home-brew scripting languages, which turn the maintenance of such projects into a nightmare.

The article suggests that it’s much better to just leave the logic in the code: this way it’s easy to read and it’s implemented in a well-known programming language.

In my opinion, both approaches are equally good – or equally bad, depending upon the circumstances.

Having business logic in the code has some very serious disadvantages. Yes, the build process is no longer as expensive as it used to be some time ago; however, the necessity to change code when a business rule changes is still unpleasant:

• Builds themselves are cheap now; however, the deployment might be quite expensive. If you need to re-deploy application to one or two servers – it’s easy; however, if the application runs in a complex environment with multiple server groups and clusters, that might be quite a different story. And if the application is actually deployed on the users’ desktops…


• Changing code might cause ripple effects, and requires regression testing – which also might be expensive.


• Frequent minor code changes under time pressure usually cause a code quality to deteriorate.


• The last, but not least: with this approach, the developers become forever responsible for implementing rule changes.

In my experience, the right solution for the problem lies (as usual) somewhere between those two approaches. There is no silver bullet, and each group of business rules (and, sometimes, even each rule) has to be addressed separately. Here are the principles I try to follow when dealing with applications with business rules.

1. Try to identify as many business rules as possible in the project you are working on. The purpose is to understand, which part of the requirements (or implementation) deals with core business logic, and which with some arbitrary business rules.


2. Estimate which elements of business rules are going to change and how often? It’s never possible to get an absolutely precise answer to this question; however, surprisingly often one can get a good estimate just by asking for it: “The states in this rule change constantly – last year we had 4 states, then two months ago we added two more, and a week ago a new regulation came out…” or “XYZ was always a special case – it’s our largest partner”.


3. Frequently changing values should go into an external location (file, database…)


4. Rarely changing values might also go there, or can be implemented as constants, whichever will make the code easier to maintain. Just do not leave them as “magic numbers”!


5. The business rules logic should be moved to separate classes, and, possibly, to separate modules. There are quite many ways to achieve it. Observer pattern can be used when the rules are to be triggered by some events. Decorator and Strategy patterns are also helpful here. Another possible approach would be using aspect-oriented programming and moving some business rules to aspects. It might also be a good idea to implement certain groups of business rules as plugins, and to make the core system automatically discover them. (I did something similar to this in one of my projects, and it worked pretty well). The basic idea behind all of this is to minimize ripple effect and make required change as small as possible.


6. If the business rules logic is subject to frequent changes, the situation becomes more serious. The design approaches suggested above will, definitely, somewhat alleviate the pain, but in general this type of situation calls for more drastic measures. Usually this involves adding some sort of scripting support and giving the users ability to write some simple scripts and script snippets. One advice for those who will go down this path: do not invent new scripting languages – first try to use an existing one. It’s also a good idea to provide some UI which will help with writing snippets and putting them in a right place. Adding scripting support and providing is, definitely, quite an effort. So, before doing this, it always makes sense to look outside of the project: sometimes frequent business rules logic changes might be prevented by fixing some business processes, or by working with users and stakeholders. It may sound unrealistic, but there are occasions when just explaining the fact that the requested changes are not as minor as the requestor thinks and do not come free of charge helps significantly reduce the frequency of change requests.


7. While following those principles, try to keep the system from turning into chaos of different techniques applied. Group similar or related business rules together, and use for each group the technique needed for the rules with maximal volatility. For example, if you have 10 similar rules, and two of them are changing frequently enough to validate usage of external configuration file for them – use it for all 10 rules. Just make sure your grouping is fine-grained enough.

Technorati tags: programming, software design

Use one editor? I prefer three...

Recently I finished reading "The Pragmatic Programmer". The book is amazing, and, probably, is worth a separate article. In short, it contains wisdom and experience of veteran programmers in condensed and purified form. I wholeheartedly agree with most of suggestions and advices the book gives; however, there are several topics on which I disagree with the authors. One such topic is the use of text editors.

The authors give the following advice:

"We think it is better to know one editor very well, and use it for all editing tasks: code, documentation, memos, system administration and so on."

In my daily work, however, I discovered that I get maximal productivity when I use not one, but three editors. Here is my setup.

1. IDE. I know some people who claim that they don’t need an IDE, and that they can achieve the same result using their favorite editor (EMACS, vi or some other). I think that those developers either never got their hands on a really good IDE, or have never done any more or less complex project. Besides simple – though also convenient – features like syntax highlighting, integrated build support, project support etc, a good IDE can provide much more complex language –oriented features. For example, my IDE of choice currently is Eclipse (I’m doing mostly Java now), and it provides me with such incredibly useful features as automated refactoring, language-oriented search, class hierarchy navigation, code generation helpers and many others. And for aspect-oriented programming having IDE with support for aspects (I use AJDT plugin for Eclipse) is vital. In my opinion, trying to program using AOP without an IDE support is a pure suicide: how would you find out that the line of the code you are about to change is, in fact, augmented by three aspects, and your change will have unnecessary side effects?

2. Programmer’s editor. Besides writing Java code, I often need to work with some other files, which do not belong to my current project. I have to analyze logs, edit data files, write some short scripts in other languages… For this tasks I use one of so-called "programmer’s editors". These are complex and powerful text editors. They usually offer syntax support of multiple languages (usually meaning "syntax highlighting", integrated FTP and, sometimes, version control support, file comparison, hex editing, built-in powerful macro languages and many other useful features. The reason why I use separate editor for those tasks instead of IDE is that (a) I don’t want to pollute my IDE workspace with unrelated files – I want to have only program-related stuff there, and (b) I don’t want to start IDE every time I need to edit a file. For some time I was a big fan of Multi-Edit; then I switched to UltraEdit and Crimson Editor. (The latter is less feature-rich than UltraEdit, but is free).
3. Notepad replacement. The third editor in my setup would be Notepad, if it wouldn’t be that crippled. The idea behind having this third editor type is that I want to have something extremely lightweight and fast, so I can instantly do some simple editing on any file. I don’t have any favorite here. Any replacement will do, as long as it supports arbitrarily large files, has support for both Windows and Unix line styles and has decent search/replace capabilities.

This is my setup. All comments and suggestions are more than welcome.

Technorati tags:programming, text editor

Joke becomes true...

Quite some time ago I’ve heard a computer joke:

Bill Gates was demonstrating his latest speech-recognition software. He was just about ready to start the demonstration and asked everyone in the room to quiet down.

Just then someone in the back of the room yelled, "Format C: Return."

Someone else chimed in: "Yes, Return!"

Unfortunately, the software worked.

I thought it to be hilarious, though highly improbable. Certainly anyone designing this kind of system would introduce some sort of protection against this kind of “accidents”, right?...

Well, today I’ve read the following:

Vista can respond to vocal commands and concern has been raised about malicious audio on websites or sent via e-mail.
In one scenario outlined by users an MP3 file of voice instructions was used to tell the PC to delete documents.
Microsoft said the exploit was "technically possible" but there was no need to worry.

The full text of the article is here, and here is a response posted on The Microsoft Security Response Center Blog.

Now I am trying to recall other computer jokes – I have to know what to be prepared for, after all…

Technorati tags: microsoft, vista, humor

Vista and downloadable games

Couple of days ago Gamasutra published quite an interesting article by Alex St. John, founder and CEO of WildTangent. In the article (called “Vista Casts a Pall on PC Gaming”), he describes serious problems which Vista will present to independent game developers (and casual game developers in general).

Two main problem areas outlined by Alex are program installation and parental control.

Installation. According to Alex, the enhanced security system of Vista might require users to enter administrative login and password every time they try to download and install game. This might sharply reduce the number of installs (and, therefore, purchases), since people might just get tired and frustrated by all the hoops they have to jump through in order to just try out a game, and, therefore, try less games.

Parental Control. It turns out that Vista has something called Game Explorer – some place where the games are being registered, which allows parents to define the allowed ESRB rating level for the games the kids are allowed to play, and which blocks the attempts to start the registered games from outside of Game Explorer. The problem here – again, according to Alex – is that since ESRB grading process is expensive, most small and indie developers cannot afford it, therefore making their games “Not Rated”. Since from the protection standpoint all “Not Rated” material is not safe, most parents will probably block it, thus locking out all small developers.

I didn’t install Vista yet (and not going to, until the time when I would have no other choice!), so I cannot validate Alex’s statements. But, assuming he is right, this might indeed have very unpleasant consequences for game developers. I have no doubt that it will be possible to turn off all these extra-protecting features, or to circumvent them. The problem, however, is that target audience for most casual games are not technical-savvy people, who will, most probably, have Vista running with default settings.

Interesting fact is that the parental control system does not apply to web games. So, if the downloadable games might lose in popularity – the web games might gain, and that, in turn, might lead to some quite interesting market shifts.

Technorati tags: Vista, games, casual games, game development

iPhone craze

It seems like everyone suddenly went crazy over iPhone. The new gadget is being discussed in multitude of blogs, newspapers publish articles on it, and the stock prices for Apple skyrocketed over the past two days. My coworkers show each other web pages with photos of the new device…

Well, I knew for quite some time that, when it comes to marketing, no one can beat the Apple guys. They are geniuses. And I am sure that the craze over this new gizmo will just increase over time, and, most probably, it will become one of the most wanted and hyped devices of this year.

But, frankly, I don’t understand what’s so great or special about this new thingy. Let’s cool down a little bit, and look at the device more attentively. Yes, there are many nice touches about it: stylish design, more or less decent on-board storage size (up to 8 Gigs), camera, Wi-Fi, Bluetooth, GPS – everything is included. You can take pictures, surf the web, play music and movies, may be even play games. There are interesting new features, such as:

• multi-touch UI;


• different built-in sensors which, for example, detect when the phone is rotated and switch automatically between portrait and landscape mode (though I assume sometimes that might be annoying);


• visual voicemail – a list of voice messages (I applaud Apple for this one!)
  integration with Google maps.

But there are also quite many drawbacks:

• operating touchscreen with fingers means having grease, scratches and fingerprints all over it. A reporter from NY Times states that “You still get finger streaks, but they’re relatively subtle and a quick wipe on your sleeve takes care of them”. The reporter was playing with the phone in an office, with clean hands. I hate to thing what will happen to the screen on a hot and humid day.


• The same reporter admits that “Typing is difficult. The letter keys are just pictures on the glass screen, so of course there’s no tactile feedback.”. The difficulty is somewhat relieved by some ultra-smart installed software – but, still, it’s not the same as having a real keyboard.


• Speaking of the software – according to Engadget, the phone is first-party software only. In my view, that diminishes the appeal of the phone tenfold.


• No removable battery


• No expandable memory


• No Exchange support


• And a hefty price tag! 600 dollars for a phone (as far as I understand, with a 2-year contract) – isn’t it too much?

And, except the visual voicemail, there are no real phone innovations in this product! (though this seems to be a problem of the mobile phone industry in general – all new features have nothing to do with telephony.) Blacklisting and whitelisting of the callers, scheduling of the notification sound types (automatically switch to vibration only at night) – those and similar features existed in crude russian Caller ID phones in mid-1990s, but none of the features is present in the ultra-modern devices.

I will not rush for the iPhone. No doubt it will have an owerwhelming success – but not with me.

Technorati tags: iPhone, apple, cellphones

Happy New Year!

(Yes, I know it's a little bit late - but better late than never, right?)

Happy New Year to all who read my blog! All the best wishes to you and your families.

One of my New Years resolutions is to blog more often - and I do hope I will be able to carry out this one.

Enjoy the life - and stay tuned!