Balloons, fishing poles, and personal empowerment.


I’m hanging out in Long Beach with a bit of Jenny’s family for a short holiday (Thursday through Sunday) to celebrate her graduation.  We’re staying with her brother who has two little guys, one 3 years old and the other 1.5 years old.  Last night the kids came home from their grandparent’s (who were acting as babysitters for the evening) house with a couple helium-filled balloons.  Of course, in the morning the balloons were no longer flying high (I can’t tell you how much that used to frustrate me as a little kid).  So, instead of tying things to the balloons to see how much weight could be added before the balloons would no longer stay afloat, the oldest boy began batting one of the balloons around in a sort of one-man volleyball game.

After an hour or so, the balloon floated a bit more out of control than previous hits and it got stuck on top of the TV.  The 3 year old couldn’t quite reach it and started pleading for support.  Now, I believe strongly in personal empowerment so rather than free the balloon for him, I suggested he use a nearby toy fishing pole to help himself.  After a few more denied requests for me to use the fishing pole to free the balloon for him, he started poking at the balloon with the toy fishing pole.  After three or four swipes the balloon was free again.  Cheers went up around the house and he seemed quite happy with himself.

What does this story have to do with anything?

Well, at the same time the 3 year old was learning how to use tools in his surroundings to solve his problems; I was answering a couple emails from people trying to use the WiX toolset.  More accurately the authors of the email were pleading for someone to provide step-by-step instructions how to solve their individual setup authoring issues.  The emails sounded amazingly similar to the little boy trying to get his balloon back.

So, I responded to the emails in much the same manner I did the three year old.  "With every drop of the Windows Installer XML toolset, there is a documentation file called WiX.chm.  You should read through that to get started.  You should also read through the Windows Installer documentation to get a solid understanding of the platform you’re building on."  Consider that documentation to be the toy fishing pole near you to free your balloon of WiX toolset questions.

Somewhere in all of the above the old saying, "You can free a boy’s balloon and he can play for another hour, or you can teach him how to use a toy fishing pole to free it himself and he will play all day" seems appropriate.  But I’m bad with fables, parables, and catchy sayings in general.  So instead all I really hope is that next time you have a question about the WiX toolset (or any other technology, really) you’ll think of the 3 year old boy who made the effort to free his balloon all by himself and do a little more reading.

Comments (11)

  1. Adam Weigert says:

    Nicely put. This is something many people lack, but there are those times when people just lack the knowledge and/or wisdom to complete the task at hand.

    However, documentation has become more complete over the years. Though there still are some areas that could use improvement. 😉

  2. Dave says:

    -And of course, there is the variant:

    "Build a man a fire, and he’ll be warm for a day. Set a man on fire, and he’ll be warm for the rest of his life." – Terry Pratchett.

  3. Peter Hancock says:

    I remember when I first started programming, and a wise boss whom I used to hound for help… I’d sit there and explain my problem to him, and then it’d miraculously solve himself. One day he gave me a duck to put on top of my monitor. He said "Next time you have a problem, explain it to the duck. If the duck can’t help you, THEN gimme a yell." Interestingly, the first time I asked for help he asked me if I’d explained it to the duck. I hadn’t, so, feeling somewhat embarrassed, I proceeded to explain it to the duck. What do you know? The duck solved the problem.

    I have one smart duck you know.

  4. jpg says:

    It seems that some of the information requests are asking for resources for Windows Installer information and not the WIX toolset.

    I may be teaching many to suck eggs, but here’s some resources on Windows Installer in general (outside of the online helpfile and the SDK’s):

    1. Mike Gunderloy wrote the first book available outside of the orginal MSI helpfile and has made this book available on his site.

    (http://www.larkware.com/installerbook.zip)

    2. Stefan Krueger (one of the few Windows Installer MVP’s) hosts a site that was oringinally based on the InstallShield product family at http://www.installsite.org but has become one of the best resources for technical information

    3. Darwin Sannoy host another site at http://www.desktopengineer.com which has some good resources for app deployments and repackaging and has some decent information about MSI’s in general.

    4. Rod Trent covered MSI’s in his book ‘SMS Installer’ also manages a site http://myitforum.techtarget.com that has a good set of resources for application deployments and custom actions (although some of the are vbs scripts…)

    5. Robert M Dickau’s posts on the InstallShield newsgroups on google. He’s one of InstallShields top technical guys if not the best who posts under psuedonym of

    i_wish_i_had_time_to_answer_individual_questions_through_e-mail_but_i_don’t some of the posts are obviously solving issues involving the installshield products, but he also covers some interesting "pure msi" problems too.

    6. Last but not least are the chats with the Windows Installer team, who also cover/help out on the MS newsgroups.

    This should give you a fair old amount of information outside of the standard WIX mailing list to find out about the Windows Installer & MSI’s in general. There are more I would normally add on, but there’s probably enough to start anyone off with…

    Hopefuly it’ll be of use to someone out there!

    jpg

  5. I always find it funny to come up with inventive new ways to compare your user base to small children/domestic animals/single cell life forms, but before you tell users to simply RTFM maybe you should make sure the manual is up to scratch.

    I agree WiX does come with a wix.chm but it’s hardly very comprehensive. There are very few cook book examples for users to copy and paste from, which are incredibly useful when starting out with a new language – especially as the idea of coding in a language that allows direct manipulation of MSI tables is a new idea to a lot of us.

    Even worse the description of wix scheme is very poor, most tables and properties have little description of there purpose or meaning. Typically if the value of a property is a string then user is often left to guess what that string should be. The custom action tag is a good example of this, 14 of its properties are of type string and only 4 of these have descriptions, while it’s obvious what some of these are others are much more obscure and can cause a range of bizarre installer errors if you get them wrong. A related problem is there are places where string values are need to reference defined id but the documentation does not say this, an example of this is the AssemblyApplication property on the File attribute this must be a valid File id but the documentation does not say this. Okay – I was able to work that one out for myself pretty easily but I’m sure there are other place where I’m missing it and am still banging my head against my monitor. Also I have come across at least one place where a property is required but is not listed as required (“Directory” on “WebVirtualDir”).

    While you may counter this argument by saying that users should read the windows installer documentation as this describes MSIs tables and properties it would be extremely useful to have this information repeated in the wix documentation, it would save a lot of flicking back and forth between the two. Also there are a number of tables supported by wix that are not listed in the Windows Installer Database Tables [1] web page such as IisWebVirtualDir (The “WebVirtualDir” node in Wix). This is particularly frustrating as I can not get a virtual dir to install even though the msi builds correctly from my script and passes the full orca validation suite.

    While I think wix good and easily the most flexible way to create your msi, I think what improve wix is a really big push on the documentation front.

    Hope this didn’t sound too much like a 3 year old boy.

    [1] http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/database_tables.asp

  6. Robert,

    First, you sound nothing like a 3 year old boy. You have done exactly what any good developer would do and read through the documentation to provide a lot of very valuable feedback about how the documentation should be improved. That behavior is very different from what I was describing in the blog entry above. I greatly value feedback such as yours and I will act on it. For example, lots of work has gone into providing more information about the CustomAction element lately since CustomActions are so terribly complex. The next WiX toolset update on SourceForge will have this and several other elements documented. However, the documentation is no substitute for a solid understanding of how the Windows Installer interacts with CustomActions as described in the Windows Installer SDK.

    The issues you bring up about the required attributes not being marked required sound like bugs to me. You should feel free to file them as such in the project (http://wix.sourceforge.net). Bugs logged get fixed (although I’ve been really busy lately and haven’t had many free cycles in the last three weeks or so). Also, the web site elements are not functional without the WiX Server CustomActions that are in my queue to finish posting to SourceForge. The documentation there will improve after the CustomActions are available.

    Fundamentally, I am quite happy to take feedback about how to improve the documentation where it is found lacking. But I do not have the cycles to spoon feed individuals (unlike you, Robert) who will not try to help themselves first.

  7. John Reardon says:

    While I agree in principle with you assertation I belive this is a different case. You would not prompt a 3yo to pick up a device that he/she has never seen before and expect them to figure out its use in a reasonable period of time. Many developers are under time contraints for the tasks that they need to accomplish and sometimes a few good (easy and complicated) examples are invaluble. I’m guessing the 3yo has seen a fishing pole before and maybe even how it is used. He has probably also seen other similar tools used in the manner needed to retreive the balloon. In contrast Wix is a somewhat different way of thinking about making a MSI install. Many people come from a GUI (installshield) background not command-line, and XML is still fairly new to many people as well.

    I guess what I’m getting at is don’t dismiss all inquiries as looking for spoon-feeding. Somtimes, when under pressure to produce, good, complex examples are much better than all the documentation.

  8. John,

    I hear you and I do my best to always answer any questions. However, sometimes questions like "How do I add a File to an MSI?" can be terribly frustrating because there are already examples just like what you note above in the WiX.chm to answer that kind of question.

    Seriously, my point was before you ask a question, pleae spend spend some time reading about what is available and how things work. I just tried to wrap it all up in a cute story. Well, my girlfriend thought it was cute.

  9. I had to do a little dig around in WiX to ngen some assembles using a custom action. In the name of caring and sharing and generally being cute I’ve made a blog entry about it. http://strangelights.com/blog/archive/2004/06/29.aspx

  10. Paul says:

    Hi,

    I’m really excited about the potential wix has. One thing I find frustrating though is that there is no complete example or best practice on how to use it. True, there are some very simple examples but they are a far cry from what someone would need to build a real installer. I think having a complete, production quality, example would help tremendously. I have no problem reading docs and looking at examples. If there was a working example, it would be much easier to manipulate it into what I needed it to be.

    Also, it would be very useful to have some templates that contain common elements. For example, there are many common UI elements that could be put in a template. That would save hours of time in developing installers.

    So, using your example, I feel like you’ve given use the fishing pole, but haven’t really shown us the best way to use it to get the balloon. Part of teaching is also showing how to use what you just taught. 🙂 Granted, given enough time, we could figure out how to use it. But so much time could be saved if we had some best practices and complete examples.

    Thanks for a great tool,

    Paul