Several people have asked that XulPlanet have a place to add comments to documentation pages, like the PHP documentation site does.
12:40 AM Bizarre article about planes and witches
I don't usually link to things I saw referenced on blogdex, since it seems kind of pointless, but this time I thought I'd make an exception. It concerns a Register article about a mother who asked about flight simulator software for her son and got visited by the police. It wasn't the events that were so disturbing, but the bizarre writing in the article itself.
I'll ignore the reference to the US being "the safest and most prosperous country in the world" because that's just asking for some political debating, which I don't want to get into. I did, however, burst out laughing when I read this line:
Julie Olearcek, a USAF Reserve pilot made the enquiry at a Staples store in Massachusetts, home to an earlier bout of hysteria, during the Salem witch trials.
I hadn't realized that the witch trials had occurred in a Staples store. I wonder what kind of office supplies they used? OK, that's probably not what was meant. I found a much better article (which will disappear soon), which suggests the event took place in a town called Colrain, Massachusetts, which is 100-120 miles from Salem. The two events seem to be completely unrelated. Why mention an event that occurred more than 300 years ago in a different location?
The better article (from the local news site recorder.com) is more detailed and makes the Staples people look less embarassing. Actually, the woman and son -- who already own flight simulator software -- had gone into the store, looked around, and then asked the clerk for software about how to fly airplanes. The Register article says that the woman had asked about Microsoft Flight Simulator. This is quite a difference. I'd imagine the local news site was more accurate than the Register article, which was 'by Andrew Orlowski in Las Vegas'. And I'd imagine that a woman asking about how to fly aircraft would be more suspicious to Staples employees than someone asking about MS Flight Simulator, the latter of which isn't referenced at all in the recorder.com article.
Perhaps the Register is under some kind of witches' curse?
6:53 PM Canvas Tag Coming Soon
Benjamin is starting to work on the canvas tag patch I wrote, so we may see it become reality soon.
12:04 AM Comments on Rapid Application Development with Mozilla
I've been going through the newly published Mozilla development book Rapid Application Development with Mozilla by Nigel McFarlane. I thought I'd add my comments.
It's very detailed. It provides detailed descriptions of XUL, XBL, RDF, templates, and so forth. For someone looking for detailed information about how to use these technologies and a bit about how they work, the book provides lots of information.
To some degree, the extra detail is also problematic. In many places, the book goes into more detail than is really necessary. There's a lot of text there. And, I think, a disproportionately small number of examples. If you were to go through the book attempting to learn XUL, I'd imagine you would be overloaded with information. Although I'm probably a little biased, I think the XUL tutorial is a better way to learn XUL, while the book is quite good for a greater understanding of the details.
I had hoped instead to see a much greater amount of focus on XPCOM and the available components. The book does provide, in the XPCOM chapter, some detail about the RDF APIs as well information about file and network reading, and provides an introduction to a number of other things, such as sockets, security and preferences. But, considering the detail in earlier chapters, this is too little I think.
However, overall, I think Rapid Application Development with Mozilla is a good addition to the Mozilla/XUL developer's library.
11:50 AM Parsing and Serializing XML Documentation
I finished the first piece of documentation that I have been working on, Parsing and Serializing XML, which describes how to parse and write out XML in Mozilla.
There are a number of other documents and have half-finished each of them, including the rest of the RDF stuff.
12:10 AM Want some documentation?
I'm now in documentation writing mode. I've been working on a couple of new Mozilla documents. I thought I'd ask if anyone had anything specific they want documented so that I can focus on that instead of writing something that no one wants.
12:36 AM Best Topicalla Screenshot Ever
I've added a much nicer looking screenshot of Topicalla, now with images and anti-aliased fonts. It shows a UI of a single FOAF file. The UI elements to use are determined from the data in the FOAF file. Some additional data is loaded from musicbrainz.org, although the loading part isn't handled automatically yet. One can select the Detail drop-down to show more detail such as the song titles on the albums, and the descriptions from the weblog.
I recently also added support for templates using XPath and XML datasources as well as the existing ReoPath and RDF support. It is generic enough now that support may be added for other kinds of datasources as well. This allows one to create a UI that is bound to some XML data. For instance, the following:
<hbox rp:repeaton="//td"> <label rp:assign="text()"/> </hbox>
5:27 PM About Documentation Seekers
There are two groups of people looking for technical documentation. The first are those looking to learn the technology. These people need to have straightforward information presented in a manner that allows them learn and understand the technology step by step. They need to start with simple examples and build to more complex ones. The documentation needs to be explanatory and not rush into introducing too many things too quickly.
This is the way I designed the XUL tutorial. It starts with simple concepts and explains them in detail so that the reader can understand them. It gradually adds new concepts over the course of the tutorial. It doesn't cover everything, but instead it tries to cover most things with more detail, as well as presenting some basic information for things like XPCOM that really need a separate guide.
The other group of documentation seekers already understand the technology and are using it. They are stuck on some problem they are having and have turned to the documentation for help. The XUL tutorial isn't designed for these people. There are two problems with a tutorial approach for this group.
First, the user doesn't know what could be causing the problem, so they won't know where to look. For instance, recently someone had a problem with a tree not rendering properly. It turned out that the problem was that the tree columns didn't have ids on them, and it was suggested that a note about this should be added to the tutorial. Actually, it's mentioned twice in the tutorial and once in the reference that ids are needed on treecol elements. The issue is that this information isn't presented where the user wanted it, especially since the user didn't know that this was the problem. I could add more notes about tree columns, but, in the context of a tutorial, it would need to be repeated in too many places.
Secondly, people looking at the documentation are looking for a answer to the problem they are having. If the documentation doesn't provide a specific answer to the specific problem the user is having, they might consider the documentation inadequate. In many cases, it's because the question is too specific to be answered by documentation. The documentation can only provide a limited number of direct responses. For instance, a topic about how to change the spacing between the icon and label in a toolbar button may be a suitable question for a theming guide, but for the XUL tutorial, this is a little specific for a direct answer. (For XUL, the actual answer is: you don't)
Anyway, here is a review of the recently published book Rapid Application Development with Mozilla. I haven't read the book yet myself, but it may provide some additional help for XUL and Mozilla developers. Although, as I said above, the problem isn't the lack of documentation, finding help depends on whether the solution to the problem is available.