The Pathological Programmer: What you don’t know can hurt other people
Documentation is hard enough when you know something about the program or function being documented. But it’s really hard if you know very little about the thing you’re talking about, or if you only know a product or service from the literature handed out by the marketing department (which is essentially the same thing).
I was reminded of this while searching for some comparison information on string types in win32 programming. I found a page on google entitled “Porting to Mac OS X from Windows Win32 API: Text” This page started out with the following paragraph:
“The most important thing you need to know about Mac OS X’s use of text is that, like the Win32 platform, Mac OS X always stores its strings in Unicode. Since your application probably uses Unicode for encoding text, you should be comfortable with Mac OS X’s use of Unicode.”
Please excuse me while I laugh hysterically: BWAHAHAHAHAHA!!!!
Anyone who has had more than a couple hours of experience of actually programming win32 apps knows that there are about a bazillion different ways of representing strings. There’s LPTSTRs, LPSZSTRs, TCHARs, BSTRs, and good old fashioned char arrays, for starters. Not to mention the uncountable legions of homegrown string libraries that one encounters when dealing with other people’s code. Of the types listed above, I don’t even have a clue which ones can store Unicode strings, nor do I know what the default unicode handling functions are for win32. It’s obvious that the guy assigned to write this page has very little experience with actually writing win32 applications. Perhaps he has some experience writing win32 apps in MFC, or something like that, but I don’t think he has enough experience to be writing a guide to porting win32 applications to OS X. In all likelihood, it’s some poor technical writer with little programming experience bugging the OS X API guys to give him some info so that he can write something about it.
If I wanted to get a win32->OS X porting guide written, I would have found an experienced win32 programmer and told him to spend 6 months to a year porting win32 apps to OS X, and then I’d have him write it.
Of course, the sad fact is that if I did that, I’d probably blow my whole documentation budget in 3 months. Sadly, most companies don’t put a lot of effort or resources into good documentation. Notable exceptions are Trolltech (with Qt) and Microsoft (with .NET).
April 5th, 2004 at 7:51 am
“If I wanted to get a win32->OS X porting guide written, I would have found an experienced win32 programmer and told him to spend 6 months to a year porting win32 apps to OS X, and then I’d have him write it.” You’d also want to have him answer questions from an experienced technical writer, who would take what the guy wrote, as well as his questions, and put together a good technical doc.