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.