prepBut nI vrbLike adjHungarian! qWhat’s artThe adjBig nProblem?

Well, I had no idea how this goofy statement had been passed around. A quick search on google turns up all sorts of hits where people have used it in their e-mail signature. I even found a guy offering T-shirts with the quote.

Anyhow, I just found the whole thing funny.

The other day I happened upon DocBook. I had heard mention of it many times before but didn’t really get what it is. Here’s what it seems to be: a well defined XML schema for writing books and such. The idea behind it is to define your document semantically rather than worrying about layout and presentation. You define chapters and books and sections and paragraphs, and DocBook tools create any kind of output you want. You can include graphics and notes and warnings, footnotes, cross references and everything. Its all very exciting.

What I particularly like about it is that you can use so many existing tools. One thing I was thinking for the mozilla world was IDL / DocBook mapping. In its simplist form, you could make an IDL file generate a DocBook API reference skeleton. If you were feeling daring, you could take the JavaDoc comments out of the IDL, and dump them into the skeleton, initializing the whole skeleton.

But if the IDL changes, is there a way to keep things in sync? The problem is that after generating a skeleton, you’d want to be able to modify the XML to your heart’s content. But as long as the XML file retains a well understood structure (which DocBook has!) then you should be able to read in the IDL and the DocBook and alert the developer/writer if the docs don’t match the source. Neat.

But for now I’m going to explore some DocBook tools and see what I can make of them.

The problem I ran into there is that the freakin’ thing doesn’t compile on cygwin. What I kept running into were all sorts of link errors:

undefined reference to
 `__static_initialization_and_destruction_0(int, int)'

After hunting around quite a bit, I discovered that this is a common cygwin error, and to fix it you need to comment out all the references to #pragma interface and #pragma implementation.

Of course! That’s what I thought it was all along. Well at least there are enough keywords here for google to index this highly, and help someone else.

Now back to mozilla doc hacking.

Disclaimer: I do not speak for mozilla.org. I do not even claim to represent the views of any other mozilla developer other than myself.

I’m sorry, but this was just too much. This message epitomizes what is wrong with most of the people who use bugzilla. I responded privately to him, and I am going to use some of the same language that I used with him. I am also going to be a bit harsh, harsher than I was with him privately.

Now to address each comment individually:

This demonstrates how little this guy understands the development process, or anything about the mozilla codebase. Anyone using bugzilla should be open-minded enough to learn a little about how this works, what a bug is, and how people can help. In the bug I outlined the steps that any developer would take to break down this problem. So many of our bugs (especially the bloat and performance bugs) have literally thousands of possible causes. To narrow those causes down to 2 or 3 possibilities is a huge help. Too often people in bugzilla say “Well, that’s a developer’s job, I’m doing testing, I’m not supposed spend my time narrowing down the problem.”

Well guess what folks, that’s bullshit. If you want a bug fixed, you’re going to have to roll up your sleeves and actually help out. What, you say you don’t have time? Also bullshit. If you have time to sign up for a bugzilla account and post “I see this problem too! Someone needs to fix it.” then you have time to try to solve the problem as well. If you have time to whine on mozillazine forums that nobody is fixing your bugs, then you have time to narrow down the cause of those bugs.

And for the supposition that a developer would find the problem in 1/100th the time? Also bullshit. Lets say, for a bug like this, that there is a single cause for this wierd allocation. The steps involved would go something like this:

1. Narrow down the cause of the problem.
2. Analyze the code
3. Fix and test the problem
4. Get code reviewed and check it in

Ok, now the issue is with #1 above. Now lets just say that a developer could narrow down the cause (using the steps I outline in the bug!) in 1 hour. The next few steps could take another 3 hours of his time. That’s 4 total hours of developer time spent working on this bug.

Now, suppose that instead one of the people reading this bug (we’ll call him “the tester”) spent 2 hours narrowing down the problem. He’s spent 2 hours of his time, sure. But now the developer only needs to spend 3 hours analyzing the code, fixing the problem and checking it in. That’s one more hour the developer can spend working on another bug. And sure, the total time spent on this is greater, and the tester’s time is not invaluble, but now that tester has a greater knowledge of how to narrow down problems and create test cases. In the future, he might be able to tackle a similar problem in only one hour.

Sadly, there is not a room somewhere full of an infinite number of developers on an infinite number of computers eventually typing out the bug fixes to every bug ever in bugzilla. And sadly, not everyone agrees on which bugs are the most important. And not quite as sadly, those mozilla developers are not at the beck and call of anyone who signs up for a bugzilla account.

There are many factors that determine if a bug is going to be fixed, not the least of which is the basic bang for the bug mentality. If you’re going to whine and bitch that your pet bug isn’t fixed, you’ve got to at least make the bug attractive for a developer to work on. And guess what, whining and bitching is not attractive. Ever.

Lets say I am a developer and their is this one bug that everyone is bitching about and posting “Me too! I hate this problem! Someone needs to fix it. This prevents me from deploying Mozilla to my mom.” Now lets even say for a moment that those people aren’t just whiny 14 year olds with nothing better to do than react to testosterone build-up, and that the bug is actually kind of a big issue.

Now lets suppose that it would take a developer who really knows his shit about 40 hours of his time to narrow down a problem, fix it, and check it in. Now lets say he’s got 20 other fairly important bugs on his plate, each of which take about 2 hours of time total. If you’re that developer, which are you going to work on? Probably the 2 hour bugs. (yeah yeah, there’s plenty of rewarding hours involved in really nailing a nasty 40 hour bug, but lets face it, most (all?) mozilla developers are men and 38 hours of foreplay is not our strength)

This is a little like Suze Orman’s advice to pay down your Morgage before you contribute to your 401k: Because in the near term, you want to have equity that you can use. If I have only 30 hours to fix bugs, and it was a 40 hour bug, guess what I still haven’t fixed any bugs. But I would have fixed 15 of those 2 hour bugs had I worked on them.

So if you want a bug fixed, make it more attractive! Take those 40 hours, figure out if you and a few other folks on #mozillazine can break down the issue and make it a 20 hour bug. Testing isn’t about finding problems. That’s only half the job. The other half is getting a best guess on what is causing those problems.

It sure is easy for people to make judgements about “Mozilla developers” and how they spend their time. But unless you’re actually helping, it doesn’t matter what you think.

I’ll write more about some of the techwriting process that I think Mozilla could adapt, but I wanted to post about LiveDocs because it is so simple, but so brilliant.

The two pieces of the application are:

1. A documentation set generated off of some FrameMaker files, and a nice UI on top of it. The UI is similar to developer documentation that you can find on MSDN. I won’t describe it here beyond explaining that it has a nice, hierarchical table of contents that is easily navigated.
2. An “Add Comment” button on the bottom of each page. This allows readers to add feedback to any page of the documentation. The brilliance of this is that authors can maintain ownership of style and content of the document, while easily being able to recieve and process feedback on the document itself.

This is definitely something that open source projects would benefit from. The fact that the files from from FrameMaker is irrelevant, but there does need to be some kind of structured means to develop hierarchicial, indexed documentation.

As an aside, a friend of mine recently was telling me about JavaDoc and how it has grown into a standard system for storing API documentation, allowing any IDE (I think Eclipse is the one he mentioned) to import documentation and integrate it into their editors or help systems. I think this is something that could be investigated as an import format for the system described above.