August 16, 2011

DocBook to WebHelp - Better HTML Books

One of the projects the DocBook community sponsored for the 2010 Google Summer of Code was DocBook WebHelp. The goal was to develop a process for generating output that resembled WebHelp from DocBook. It resulted in a process that generated HTML output that uses jQuery to create a collapsible TOC and Apache Lucene to create a full text search index. It is slick.
The FuseSource documentation had been using HTML frames to accomplish something similar since we were part of IONA. While it looked good and got the job done, it was not a great solution. Some people complained that the frames didn't work in their browsers. We got complaints that it was hard to bookmark pages or to get links to send in e-mail. There were also complaints that the documentation looked very 1999.
So, a few months ago I started looking at what it would take to modify the FuseSource HTML publication process to use the DocBook WebHelp tools. It took a little doing because we have a pretty hefty customization layer, but all in all it was pretty easy. The guys on the DocBook mailing list were very helpful.
We started rolling out the new templates with the Fuse IDE 2.0 documentation . In the coming months the template will be rolled out across all of the FuseSource documentation.
The new WebHelp based HTML output is pretty slick. We added Disqus powered comment forms as well. They are not perfect, but incremental change is the name of the game. As we get feedback from customers, we will work to make them perfect.

User Interfaces

I've been reading an excellent book about bicycles, fiddling around with different kayak paddles, getting used to Lion, and looking for a writing program for my iPad. All of which got me thinking about user interfaces. Yes, bicycles and kayaks have user interfaces.
I've always believed that the user interface is the most important part of a product to get right. If the user interface is bad, it doesn't matter how efficient, powerful, elegantly designed, or feature rich a product is. If using it is harder than it needs to be, confusing, or generally less pleasant than other alternatives, very few people will use the product.
Kayak paddles are a good example of the generally less pleasant than other alternatives. There are hundreds of different kayak paddles on the market. Every paddler I know has one, maybe two, that they will choose to use. Other paddles may do if there is no other alternative. Why is this? It is usually subtle things that get described in fuzzy terms like the feel of the paddle as it moves through the water or the balance or the impression of it's power. The important thing for this post is that the subtle things make a huge difference to the user. I may prefer how a skinny wooden paddle feels and my friend may prefer how a scoopy carbon fiber paddle feels. So we make different trade offs for the feel.
Shifting systems on bicycles are similar. Shimano shifters use two levers for each derailure while SRAM uses one. I personally found the SRAM confusing, but the guy at the bike shop thought the SRAM system was better. Again, we make trade offs because of a user interface difference.
Bicycle shifting systems can illustrate a larger piece of why user interface is so critical. When I was in college they introduced index shifting-the lever clicked into place when the lever was "in gear". It made shifting a lot easier, except when things were out of tune, because you didn't have to guess about when you were in gear. When things were out of tune things shifting sucked, but it was worth the trade off. Later they moved the shifters from the frame and integrated them into the brakes. This was a major improvement because you didn't have to move your hands off the steering to shift. There are trade offs here too, but the improvement is well worth it. So a few little changes made a gigantic difference in the interface between the bicycle and the rider. Bicyclists are now more efficient and safer.
The user interface in software is even more critical than on a bicycle or a kayak. The user interface is in many ways all there is to the software from a users perspective.
Take the operating systems for example. Unix geeks will tell you all the super important things that operating systems do like efficient file systems and sandboxing apps for security and networking and blah blah blah. It is not that those things are not important, it's that most users do not care. The reason a user picks Windows or OS X or Ubuntu is largely because of how the user interface feels to use. Yes, there is some consideration of "will my software run on this thing" and that may be the deciding factor, but feel is critical as well. At work I'm a Windows user and for a long time I used Windows at home as well. The reason was that I was familiar with Windows and none of the Linux desktops proved to be worth the learning curve. I didn't know enough about OS X to spend the money. That changed when I met my wife. She had a Mac and after using it for a few weeks I was hooked. Why? It had nothing to do with it being more powerful, or more secure, or any of that. It was because it felt better to use. The little details made me happy and it all seemed more intuitive.
The same is true of writing programs. I pretty much hate Word and Open Office and FrameMaker. They are bloated, ugly, and unintuitive. I actually prefer using text editors over any of them. They all suffer from a similar problem: the features get in the way of the core mission of writing. Even when the features are supposed to help the core function of writing they get in the way. Take the autocorrect. It just changes the word under your fingers instead of simply underlining the word.
What I'm getting at that a UI needs to make completing the core task of the tool easy and enjoyable. Anything that gets in the way of accomplishing the core task of the tool should be eliminated. This of course means that the product's feature set must be properly assessed and the core task identified. Once the UI is stripped down to minimum required to facilitate the accomplishing the goal, the details that make doing the job enjoyable need to be added. For example, nice icons, readable text, and sensible animations that provide feedback without being distracting all make interacting with a tool more enjoyable.
Nailing the UI makes the difference between being the iPod and an MP3 player.

August 14, 2011

Fuse IDE Videos

The FuseSource doc team has been working on perfecting our ability to make high quality video tutorials. I tried a free tool called Wink which did OK, but lacked the polish of professional tools.
Part of the problem was also my lack of voice talent. My voice is perfect for mime and I really have a hard time reading off of a script - even one that I wrote.
Fintan Bolton started using Camtasia about a month ago and has had much better luck. Camtasia has some excellent editing and production tools. It can do zooms and transitions. It also has some nice audio editing tools.
Fintan also has an excellent voice talent on hand. His wife has a good radio voice and she can read a script well. Her voice over is clear and easy on the ears.
He has done two excellent videos that show Fuse IDE in action:
* Message Browsing and Tracing
* Throttler EIP