Programmer Symptom: Weak Documentation and Support

Below is a letter written by me to a local software house which had sold us their SDK. This company had quite a solid product, but they fall in the trap of being too development/technical centric. I have no doubt they have pretty good programmers on the team, but they suffer the downfall of Programmer Symptom: Weak Documentation and Support. Usually you could escape easily when you are selling a end user product, but sadly they sell SDK (Development Platform). I hope this would enlighten some of you out there who are trying to make a living by making commercial SDK.

---

We have been using Product X for about 1 month plus, and we found great difficulty in trying to master it mainly due to the lack of API documentation and sample codes.
The following is some of our suggestion to improve the usability of Product X Development tool.

1. Product X Developer Portal
Since Product X is not an Open Source project, it lacks the developer community's support. Plus, we could not find help/reference anyplace else besides Company X. If you don't provide enough support and resources, we are basically trapped and helpless. Thus we would suggest you create a developer-centric portal which focus on Product X's latest release/patch/tools, programming article/resource and alike. Spare us the sales material. At lease we have a centralised site for all latest Product X material, rather than me have to keep the bit and pieces of update from email to my local harddrives. I might even suspect I don't have the latest full kit.

2. Forum
The current forum should be a compliment to the Product X Developer Portal. Since there is insufficient documentation and sample code, the Forum would be our only source of knowledge (thus we depend heavily on it). But, we would appreciate fast response regarding our posting, as it is quite frustrating if we did receive any useful response within a timely matter (please remember that we depend on it a lot at this moment, it is our only hope). It would be nice to have a response time of 24 hours, as anything more than that prolong our agony and disrupt our progress. In fact, a responsible personal should be appointed to monitor the forum in a daily manner (he will be responsible to remind the developer to reply to the forum, and make sure all queries are responded in a timely manner - leave no stone unturned).

3. Documentation
I have to be frank about this: Product X documentation is weak. The Javadoc lack of useful description, especially using some of the more obscure and advance method. I am totally lost and have absolutely no idea how to use those API, and have to keep guessing and experimenting (a big setback in terms of productivity). I understand that programmer naturally don't like to do documentation, but this situation had got to improve (you are selling a development platform with APIs, and we need to understand them in order to use them). What I would suggest is to hire a newbie programmer with good documentation skill to learn how to use Product X, thus enhance on the documentation while he is learning how to use it (for every questions asked by him to the Product X Team is the questions faced by other developers, document those down and share with the rest). Basically, you need a dedicated person to do documentation for Product X (a superb technology serves no purpose if no one could master it except its original developer). At the same time, he could create more sample code using Product X to be shared out with the Product X Community as well. Probably you could consider releasing a book on how to use Product X (try to get someone with experience writing technical book or tutorial, else it might become disasterous), step by step tutorial style. That would save on your training and support cost for the long term. Successful open-source project such as Strusts, Spring and Hibernate had good documentation (not perfect), numerous tutorials from various author, active forum and centrailised resources.

4. Sample Code
Sample code is the flesh and blood of a SDK, probably more important than the documentation itself. I can live with lousy documentation, but I certainly cannot live without sample codes. Product X does provide some very basic sample codes, but these sample codes lack real-life practicality and demonstration of advance feature. I know of Company X created many Product X DEMOs for various projects, why not release these samples (with source code of course) in the Product X Developer Portal for the community. At lease these sample codes are more advance and "real-life" compared to those which come with the SDK. What do I mean by real-life? For example, how could I use Product XDB to extract data from a joint table (mix with SUM, GROUP BY, CASE) and display it using NETable (want to show total as well at the last row), and allow user to edit it and update back to the database. Frankly, I haven't figure out how to complete the entire process. At first I bump into problems using Product XDB for joint table (Product XDB documentation is much weaker than Product X, and samples are either incomplete or almost inexistance), until I totally give up on it and use Hibernate instead (the engine is more superior, with great support, but its architecture don't quite fit into Product X's client server environment - much to be researched on). Now, I am using Hibernate but facing some undocumented problem using editable NETable and waiting response from the forum. We need useful real-life application sample using Product X, not some newbie sample, which don't quite serve any purpose. Besides releasing the DEMO samples, you could have a dedicated person writing documentation and creating real-life application samples for the community (based on feedback from the community). Having done this not only increase the usability of Product X, but it reduce the support strain on your development teams with all these Product X queries bombarding their email and forum (which might frustrate them and disrupt their daily work and productivity as well).


If Product X is ever to be a widely used SDK/Product, you would probably need to put more effort and investment in helping the developers to master your product. I know documentation is not everyone's cup of tea, but someone have to do the dirty work (and make sure he is an expert of dirty work). If I ever found an average Rich Client product (even though Product X is much superior) with good support (documentation, code samples, huge user base), I would probably abandoned Product X (just like the case for Product XDB). I think I kind of know Product XDB is more suited for Product X's Architecture compared to Hibernate, but I really don't have a choice (because I don't know how to use the more complex feature of Product XDB). Currently I think the only way for me to increase productivity is to rent a cubicle in Company X so that I can have an expert next to me whenever I faced a problem (I might just suggest that if I am desperate enough).

I sincerely appeal to you to consider my recommendations and make Product X a more developer friendly product. Your attention and swift action is greatly appreciated.

I think Product X is quite a good product, it is ashame to let it down due to poor support.