Confusing Marketing

Ok sometime I see something and just want to say what the heck. Palm's marketing copy for their Centro is one of those things.

The Centro's product page says the following:

Life starts after five o'clock. That's why there's the Palm® Centro™ smartphone. Palm Centro gives you voice, text, IM, email and web, all in a phone that's a lot smaller than you think. It even has a touchscreen and a full keyboard, so you can say L8R to those tricky keys on your cell phone. Carry names and numbers, shoot photos and video, and meet up with friends. Centro. Let's go.

What were they thinking? If you have a smart phone, you generally use it because you are a workaholic. You don't use it for you outside the office life. Even if it is a toy you use to communicate with your friends, you're probably using it to check your rss feeds or myspace messages when you should be talking to the girl sitting next to you, since its 5 o'clock and that means its happy hour.

A tale of bad documentation - Part 2

In part 1 I discussed a real life story of bad documentation wasting peoples time. In part 2 I provide an update and some notes on the more human side of this all.

After some correspondence on the mailing lists, I submitted a documentation patch. There might an iteration or two of changes to that, but I expect it to make it into the final product (the website) in short order.

All in all its been a mostly positive experience as far as interacting with people. The people on the list were pretty helpful and quite responsive. However, the tools were a bit obtuse. I'm hoping to be able to help fix that fir future releases.

A tale of bad documentation

I am a programmer by day for a small software company. By night I write open source software. I guess I like to program.

I once submitted a patch to an open source program called XML Copy Editor. It was small. Soon afterwards I volunteered to perform a small task and was given developer access to the source repository. I continue to correspond with the developer although I've only made that one original change to the programs source code.

My latest non code contribution was helping the author replace MSXML with Xerces on Windows. I originally expected to have to fight with Xerces, but by dumb luck the first thing I tried worked after a bit of tinkering. The reason that the programs author had trouble using Xerces on windows was not because of bad code or bad make files. It was because of bad documentation.

Because of bad documentation many hours were wasted by him that could have been dedicated to making XML Copy Editor better, or any other task he chose to spend his leisure time on. Because of bad documentation XML Copy Editor has fewer features than it could have. Because of bad documentation I am writing this post.

Now I decided to allow some good come out of this situation. As you all know, I decided to use this as a lesson delivered by the blog article you now read. In addition, I shared my story with the Xerces-C developers mailing list and offered to correct the situation.

Now if you read my email and the documentation I refer to, you will probably come to the conclusion that the documentation is quite good, except for this one oversite. You would be correct. However, the oversite was for common usage scenario, and caused significant harm to one developer and his user base in terms of wasted time. Since the documentation fails to cover the usage senario I care about, the documentation fails to address my needs. Therefore I could have been alienated by the documentations small oversite.