Tuesday, December 11, 2007

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: ,

Monday, December 03, 2007

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: , , ,