Neil's Place

December 15, 2003

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.

Comments ( 7 )

December 11, 2003

Chrome Registry Thoughts
Some interesting ideas for better handling of Seamonkey/Firebird apps and extensions.

8:40 PM Buying a CD

I have never bought any audio CDs. Nor have I bought any audio tapes nor any records. Neither have I bought audio on any other medium. Nor, for that matter, any DVDs or videos. I don't own a CD player. And I don't have an MP3 player. I have also, if you would believe, never downloaded any music illegally.

Recently, I listened to some music that I found on the Internet. Yesterday, I decided that I liked what I heard enough that I decided to buy the CD for myself. Of course, I've never done that before.

Recording studios would have you believe that no-one would do that. They would rather tell you over and over that people download lots of illegally copied music instead. That may be true, but that isn't true for me. I'd imagine that the music industry wouldn't even believe me. Well, I have only one thing to say to that.

Comments ( 5 )

December 8, 2003

User Interface Hierarchies Rant
Interesting thoughts on simplifying UI.

December 6, 2003

1:08 AM I've changed all URIs in the XUL tutorial

When I originally wrote most of the XUL tutorial, I really didn't understand RDF that well. Now I do. At the time, I used URIs in my example RDF that were of the form 'urn:something:thing', since that is the form that some of resources in Mozilla used. That was actually a bad idea. Specifically, you're not supposed to make up the parts of a 'urn', except for the last part. The word between the two colons ('something' in 'urn:something:thing') is supposed to be one of a specific set of values as defined in RFC 3406.

Secondly, 'urn:animals:root' for instance, is very generic. Much too generic for a resource URI, since it should be globally unique. Better would be to include the domain of the person or entity that created the resource, which is what is usually done. I myself might use 'http://www.xulplanet.com/rdf/' as the base of all URIs. So, I have searched through the tutorial and have changed all 'urn' references to 'http://www.xulplanet.com/rdf/' including those in the animals example.

I originally wasn't going to change them, as I figured they were just examples. But, of course, after four years of questions and confused people, I realize that very few people using XUL, RDF and templates, even seem to take time to understand RDF very well.

I've noticed that many people are using 'urn' resources such as 'urn:music:item1', which are not good resource URIs. So hopefully, by changing the tutorial, I can discourage that usage.

Comments ( 26 )

December 5, 2003

Bug 53673 is fixed
The 'multiline textbox does not accept initial value' bug

December 4, 2003

12:08 AM First draft of canvas tag patch

I put together a first draft of the XUL canvas tag patch. I also added a few examples. I haven't tested patching and then compiling since I've never been able to get patches to apply properly. So I can't guarantee that it will work right. I can only compile on Linux myself but I've hopefully got the Windows/Mac/OS2 changes right. The patch was created against Mozilla 1.5 since that's what I'm using for something else.

The canvas works fairly well, although some features crash (drawing polygons). If anybody has a chance to try it, let me know. Or, if you have bug fixes, especially on various platforms.

Comments ( 30 )

November 29, 2003

Is Mozilla Development Too Hard?
Not really. There's over 100 extensions that show it can't be that difficult.

12:22 AM Canvas Tag Update

I tend to get carried away when I work on something I think is really useful and interesting. Such is the case with the XUL canvas tag I'm working on. Joe Hewitt's original version creates a simple image buffer which can be drawn into using a few drawing functions. My updated version can do that, but also quite a bit more. It supports lots of drawing functions to draw lines, text and images, as well as pixel drawing.

The canvas also supports custom layouts, which can be used to position and size the children of the canvas in interesting ways. XUL doesn't really need this capability -- it's various layout types are quite suitable. However, there was another task I was working on where I realized it would be very useful to be able to use a simpler set of layout tags, where the complexity was hidden behind a custom layout. With the canvas, this custom layout is done in XBL. Actually, I designed the canvas such that one could create custom elements where the actual painting and layout was hidden in XBL.

In fact, I managed to implement a few XAML elements such as GridLayout using the canvas, and was successfully able to display some of the XAML examples from the MSDN documentation completely unmodified. OK, I only implemented the very basics of the examples, but there's potential for some interesting things. Note that I'm not trying to create a XUL-XAML layer -- that would be almost impossible.

Since I don't have CVS write access to the Mozilla, I'm not sure if there's an easy way of creating a patch. So I may have to zip everything up and then hope that I haven't missed something.

Comments ( 13 )

November 28, 2003

1:36 PM nsIObservers Info

I added a small bit of documentation on nsIObservers , which can be used to listen to and notify about global topics in Mozilla.

Comments ( 7 )

November 26, 2003

6:59 PM Browser as Component

Many internal company applications require some component, or extra installation to be done before the application can be used by employees. There are many Web sites that use content that need a plugin. For example, there's lots of Flash, Quicktime, Real video files, Adobe PDF's around. To view them, you either need to install a plugin or perhaps it was included with the browser. Often, a certain version is required (Flash 6, for instance). For internal corporate tools. there's all kinds of speciaalized components that are used. Many applications are written in Java, or Python or whatnot, and require a runtime of some sort to be installed.

Nobody seems to have a problem with requiring that users have such plugins installed. Web sites will just point you to where they can be downloaded. When it comes to browsers, however, people seem to have a notion that browser usage is a either-or thing. You can use either one browser or another, but you can't use both.

But who says you can't use lots of different browsers? Do I even need to have a default browser set? If an application that I need to use wants an Opera HTML/CSS engine, I'll download one and use it. Why does it matter that I don't use Opera to browse the web? There are all these web-based applications that seem to demand that you be using IE as well as some specialized ActiveX controls. But is it really a web application, if it has such requirements? What's the difference between that and requiring that someone be using Mozilla Firebird?

In the last poll, someone seemed to think that XUL couldn't be used by people who normally use IE. This isn't logical. There's no reason an application couldn't insist on the appropriate browser or browser component to be installed, as with plugins. Many XUL features will work, for instance, in the Mozilla ActiveX Control. There are many applications that require downloads first. Why should browsers be any different? On one hand, I could insist that someone have IE 6 on Windows, with an extra component installed to do more specialized UI, or I could just require they have Mozilla and write the application in XUL.

Is it a download size thing? Surely not. Both Opera and Mozilla Firebird are about the same size or a smaller download than Real Player, Quick Time, Acrobat, and many other plugins.

This is why I think a proper GRE is a good idea. If Gecko could be treated as a simple component that can be used with other architectures, it will better be able to distance itself from being a browser that people think you can only have one of.

Comments ( 5 )

November 24, 2003

Mozquery
A project to make some Mozilla RDF creation and query tools. I wonder if ReoPath could fit into it in some way.

November 22, 2003

1:12 PM What I'm going to do

I think I'm going to take the Netscape Communicator source code and make it Open source. That way anybody can use it, change it and distribute it openly. Then I'm going to create a UI markup language and call it XUL. Then, I'm going to promote everything so that other companies like IBM, Sun and Redhat want to help out. As well as lots of independent news sites, documentation sites and projects. All of them will come together to form a number of Alliances.

Then, more open, XUL-based projects, perhaps hosted on a site that provides free hosting for such things, will be created, and each will form their own alliances. I think I'll call these Open XUL Alliances.

Then, we'll need a way to bring the alliances together, since using a generic term to refer to all things that are open, about XUL, and has groups of people, would be a good idea. To to this, I'll hire someone who works at Opera to create a site openxulalliancealliance.com.

That would be a lot of work though. Maybe I'll just go cause trouble in some newsgroups instead.

Comments ( 17 )