April 11, 2012

Fuse Enterprise and EPubs

FuseSource just released a public beta of our Enterprise open source integration products. The idea behind the Enterprise versions of the products is to make the underlying Apache software more accessible for typical enterprise customers. A big part of that push was around improving the documentation and examples. We took a long look at our content and tried to reorganize it to be more user task oriented as opposed to feature oriented. We also tried to add more "intro" level content. It was quite a bit of work and it is still on going.
Another thing the doc team added to make the content more accessible is add a new publication format: EPUb. All of the documentation for the enterprise products are available in EPub and look great on iPads. Most of the work for making this happen was done by the excellent people who work on the DocBook XSLT project. Using the work they did on transforming DocBook into EPub along with help from them on the mailing list, I managed to integrate the EPub transforms into our publication system.
Check them out at Fuse MQ Enterprise Documentation and Fuse ESB Enterprise Documentation

March 2, 2012

Keeping Track of Everything

It is no secret that I suffer from gadgetophilia. What is a little surprising to me is my love of data. I always thought that tracking a paddle on GPS was useful while on the water, and it was fun to see your speed at the end of the trip. I never really thought I'd be interested in that data later.
A few years ago I got a Garmin Forerunner as a cycling computer. It track cadence, speed, heart rate, and your course. It also let's you down load the data to a computer for tracking your workouts. I figured what the heck, it would be cool to see where I've been riding. Now, I have three years of ride data and I constantly compare new rides with past rides to track my progress. It is a little bit of an obsession.
I've also been keeping track of my weight because my doctor told me it was the best way to diet. Seeing the trend line would keep me motivated. It never really worked, but I did it anyway. The graph was sort of neat. When our scale died a few weeks ago, I wanted one that would automatically track my weight. I ended up with the Withings scale. It records weight, BMI, and body composition data and automatically uploads it to the Web. I find this super cool and love looking at the graph.
This obsession with data extends to photos as well. I love the way iPhoto can show where a picture was taken and I love the fact that my iPhone automatically ads that information. It save me from compulsively adding the data manually. If I have to I do while I'm adding face data, because that is super cool too.
Initially I worried that maybe keeping track of all this stuff was unhealthy; it was just another time killing obsession. As I thought about it more I realized that it was just another form of journalling in a sense and that some of the data was actually helpful. In fact, human beings have been obsessed with keeping track of things forever. Technology just makes it easier.
I have always been a journal keeper. Writing things down started out as a crazy teenage dream about having source material for an autobiography for when I was famous. Then it became a creative outlet and a way to work out the stresses of life. The journal is also a good way to keep things in perspective. It provides a window to the past, both good and bad, that can help refocus what is happening in the present. It can also provide clues as to what is happening in the present-sort of like medical records.
The face and places data with the photos serves a similar role. It provides context for the pictures. It adds to the memory. It also makes the photos easier to find.
The workout data and the weight data doesn't serve a real memory purpose, but they do help in keeping track of your health. I can easily see that last summer I was in better shape than I am now. That is no surprise since the stationary bike is easier than a real bike. I can also easily see that I am in better shape at this year than I was at the same time last year. So, when I drag the real bike out of the garage, I will be able to gage what is a good starting point for training. When my health anxiety gets going good I can see proof that I'm in good physical shape.
I think that the data craze is here to stay and not just for me. Anyone can keep and track reams of data about themselves cheaply and easily. For a hundred dollars you can buy a wrist band that monitors your activity throughout the day and monitor the quality of your sleep. With a smartphone you do even more.
Applications like Facebook, Pintrest, and Intagram are more ways we keep records of our lives. They are taking the place of journals, folders, and photo albums. Just easier to update, store, and share.
Of course the downside of all this is that companies now have access to all of this information too. When it was written on paper in your drawer or in your bookcase, you controlled access to the information. Now Facebook, Google, Apple, Garmin, Fitbit, and other companies can use the data for their own ends. You just have to trust them to be good shepherds and not sell your data to the wolves.
That is probably easier with companies that view you as their customer instead of their product.... So it pays to know the business model of the companies who have your data.

February 21, 2012

Content Management

In addition to the complexity of gathering, organizing, and presenting technical information, technical writers have to deal with managing multiple versions of the same content. Sometimes the versions correspond to different versions of a product and sometimes they are tied to different products. For example we maintain documentation for at least two versions of four different products. Two of the products share content with a third product. Keeping track of what version of a document goes where and where to make changes so that they apply to the proper products and versions is complicated.
For the last ten years, I have worked at companies that use a source control system for documentation content management. In general, source control systems are a good match for a documentation content management system. They use a centralized repository for storing content objects. They provide change tracking and versioning. They provide mechanisms for managing and viewing different versions of the same set of content objects.
I personally have used ClearCase, Subversion, and Git. They all have done the job asked of them. In ClearCase we didn't really tax the system much. We were working with FrameMaker BLOBs and only working on a single version of the content at a time. We also relied on the build team to manage the view specs, the branching, the tagging, etc. We used Subversion in the same way we used ClearCase, but slowly started working with XML content objects that were shared across product lines. Things got trickier once we started sharing content and we lost the team that managed the views and the branching. By the time we got to Git, we were completely on our own managing a spaghetti of branches and tags.
The drawback to all of them is that they are tailored to being used by developers. The interfaces are hard to use and non-intuitive to writers. They also lack a lot features that writers need like searching content and flow control. For example, to get the proper view of a content library in SVN we had to write and maintain checkout scripts to get the proper versions of all the proper repositories. If you worked on multiple versions of a product, you needed to have multiple working copies. It works well when it is all set up properly, but it is a major pain point. It is also fragile. It is easy to make a mistake that breaks a lot of things and is hard to undo.
There has to be a better way. I had always heard that there were products that are tailored for managing documentation content, but never had budget.
Recently, I have started investigating CMS systems. The first trouble was figuring out what type of content management system. There are Web content management systems that are used to build Web sites. There are enterprise content management systems like Share Point that are designed to store all sorts of content objects.
I am interested in component content management systems. This type of system stores content modules that can be assembled into final documents. They typically use XML as the content model and provide features for dynamic ID generation and linking. They also typically offer hooks into the major XML editors. They also offer searching and process control features.
I don't expect that any system will completely hide the ugliness of managing multiple versions of a diverse set of content. It is an inherently tricky problem. There will always be the problem of maintaining a coherent methodology for identifying variants and making sure changes get applied to the proper variants, etc. My hope is that a CMS system places a more friendly veneer over the process so that it is easier for a writer to work with.
I'd rather have writers focused on content than on managing the versions of the content.

February 1, 2012

Difficult Things

For me the hardest writing task is rewriting old material. I'm not talking about updating something because the feature changed. I'm talking about reworking and reorganizing material that needs to be updated to fit into a new structure or that needs updating because it just needs to be better.
Writing new content is difficult. The cold stare of a blank space is unnerving. The research that needs to be done before writing even starts can be grueling. The reviews are sometimes long and require rerunning the gauntlet.
The challenge of staring down the blank page and getting to the end of the race is exhilarating. Learning the new information and filling up the page gives me an endorphin rush. The anticipation of the reviews makes the thrill of a good review huge and the challenge of addressing the review comments a savory challenge. The sense of accomplishment makes the pain worth it. Of course it also helps that writing new content does require quite as much groveling during resource planning meetings.
Reworking old content does require a good amount of groveling and doesn't have the same payouts. The endorphins don't rush; they trickle. The sense of accomplishment is hollow because all there is to show for the time spent is a shinier version of the stuff you already had.
Not only is the reward less, The rewriting is also just plain hard. Often times you need to relearn the feature or concept being discussed. You always have to make judgement calls about what information to cut or add. Then there is the angst of reworking another writers (you were another writer when you wrote the original content, time changes every craftsman) handiwork. The cold stare of a page full of words that you need to slay is unnerving and unforgiving.
If you do the rewrite well, then the suffering is worth it. You will have made a significant improvement to the quality of the documentation set. If you it OK, you may or may not have made an improvement. You just spent time spinning your wheels. Often times you will never get any feedback to know finite was well done or not. You will just have to decide on your own.
For me the answer is always that I could have done it better. Nothing is ever perfect and I'm always improving/growing/changing as a writer. I always look at the end result as good enough for now. Maybe that is why I don't write fiction or for magazines or newspapers. In those mediums you finish a piece and are done with it. In technical writing, at least in 21st century Web only technical writing, no piece of content is ever truly finished.

January 12, 2012

FuseSource has Documentation

I find it frustrating that so few people, people who use our products, realize the amount of documentation FuseSource offers on their products. I was talking to some users the other day who were shocked to discover that FuseSource offerers Javadoc for Fuse ESB.
It rapidly becomes clear that people who complain about our documentation are usually complaining about the documentation they find at the Apache projects that make up the core of our offerings. I understand their frustration with the information on the Apache sites. It is often outdated, confusing, and hard to search. It is written by ninjas for other ninjas.
The FuseSource Documentation team writes professional, versioned content targeted at more typical corporate IT professionals. We strive to make the content task oriented and relevant. We use better sample code, vet the content for accuracy, and organize it so that it can be searched effectively.
Our documentation can be found at:
Fuse ESB
Fuse Message Broker
Fuse Mediation Router
Fuse Services Framework
It is available for free and, hopefully, is useful. We love to get feedback, so if you find issues or have ideas about how we can improve the content, leave feedback in the comment forms on the bottom of the pages. One of the writers will get back to you pretty quick.

January 5, 2012

The Value of Documentation

I have to give a presentation about how documentation adds value to a product offering. The fact that documentation adds value seems like a no brainier until you have to explain what that values looks like. My initial thought was to simply say that documentation educates the customers and makes it possible for customer to use the product. However, that answer doesn't fill a half-hour presentation or do justice to all the ways that good documentation helps a product and the company as a whole. The places documentation adds value are throughout the product life cycle:
  • it helps marketing by increasing the number of Web search hits the product shows up in
  • it helps sales by providing education and evaluation materials that prospects can access
  • it helps sales by making it possible for a customer to do there own POCs
  • it helps customer service because he customers will call with fewer issues and many of the issues can be resolved with a link to the documentation
  • it helps development by finding rough spots in user interfaces
  • it helps development find bugs because the doc team is a pseudo QA team
  • it helps bring new hires up to speed quickly
Basically, a good documentation team does more than just create a bunch of words that nobody reads. It makes the customer's experience smoother and thereby makes all of the other functions around the product easier to accomplish. Good documentation adds value by freeing up other parts of the organization to do harder things.

December 22, 2011

How to Build a House

We get a lot of feedback saying that customers want cookbooks. They want documentation that tells them how to solve a problem. They are not complaining that the documentation doesn't cover all of the features they need to use. They are complaining because they don't know which features to use and how to use them to solve the problem. How to address this feedback? Write cookbooks? For a typically resource starved doc team that would mean sacrificing feature documentation. Product managers generally frown on that. Besides cookbooks tend to have too narrow a focus for a general audience. Ignore the feedback and hold on to the belief that it is only a vocal few who aren't satisfied with the feature documentation? That won't stop the complaints. It also doesn't address the problem of users not knowing what to use when. It doesn't help users know how to use the product in a real sense. You could reframe how you approach the task of documenting the product. Instead of starting from "how do I use feature x?" can we start from "how do I solve problem y with feature x?"? I think you get documentation that satisfies both the users who want to know how to solve problems and the product managers who want the features documented. This approach is not easy. The difficulties start with the list of things we are given to write about. Typically the product manager hands out a list of features with little explanation of what problem they address for the users. I've seen lists that say things like "support WS-Security" with no statement of why that is useful. The writer needs to drag the use case for the feature out of the product manager if they know it. The writer has to also know enough about the product domain to have a general sense of what problems users are trying to solve. Once we figure out what people want or need to do with our products, documenting the features as part of building a solution should provide comprehensive coverage. There will still be bots that describe how to use an individual feature and there will still be reference material. It will just be organized around the idea of building a solution instead of using a toolkit. One question I was asked was about "less popular" features. My answer was that if a feature is used to solve a customer's problem it will get covered. If it doesn't solve a problem then maybe product management should consider yanking it.

December 15, 2011

Bit Literacy by Mark Hurst

I downloaded this book from Apple because it sounded interesting and it was free. It is not the sort of book I would pay money to read. The description made it clear that this was a book with something to sell.
Bit literacy is the product and Hurst's company will gladly sell it to your company for a hefty fee. I don't begrudge Hurst for this or think any less of him, but I don't ever feel like paying for a marketing tool.
It turns out that the book has some good stuff in it. It also doesn't shy away from offering up details on using the system. So, if you are buried under bits(e-mail, photos, power points, etc) it may be worth paying a few
bucks.
The key to the whole system is rooted in standard productivity lore. Let the unimportant stuff vanish so you can focus on getting things done. Don't keep ten pictures of the same thing; only keep the best one. Don't save every scrap of e-mail because it buries the stuff you need to save.
Hurst is a proponent of inbox zero. You should empty your inbox at least once a day. E-mails are either junk to be discarded, to do items that need to be tracked, or information to b stored in an appropriate place. The inbox is not a place to keep to do items or information.
One other discussion I found interesting was the discussion of file formats for textual data. Hurst comes right out and says that Word, and its ilk, are never the proper choice for sharing text. He prefers plain text unless you require formatting. If formatting is required he prefers PDF.
Bit Literacy has some interesting ideas for writers as well. Hurst has a whole section on how to write in a bit literate manner. Basically it is all about front loading the point and brevity. Write in a way that respects that the reader is busy. This is not about pleasure it is about efficiency.
Hurst's book has some worthwhile points. There is something in there for anyone who uses a computer.

October 28, 2011

Fuse Message Broker Update

I pushed out a big update to the Fuse Message Broker library today. It includes a new product introduction that should be more informative. It also includes the first stab at documentation for administrators. Naturally, there are a collection of other little updates.
The long term goal is to reorganize the existing content to be more task oriented. That will happen as we fill in the gaps over the next year.

October 19, 2011

Goggle Docs Mobile

Yesterday I had to do some reasonably simple edits to a document in Google Docs, but I was away from my computer. I didn't think much of it since I had my iPad and Google Docs supposedly has a mobile interface.
Let's just say that I have significantly less hair after the experience. The mobile version of Google Docs was better before they allowed "editing". Now all you can do is add text to a document that doesn't have tables. You cannot add formatting or do any sort of work with a table-even the rudimentary stuff you can do in the desktop version. The document management features are similarly hobbled. I don't see the point unless it is to encourage people to use Android powered gadgets.
In frustration, I decided to switch to the desktop version of Google Docs figuring the iPad's screen was big enough. Sadly I kept getting scripting warnings. Sometimes I would get a few minutes before things went pare shaped. Often, however, I could barely get the interface to load. It was crappy all around.
I don't see the point in offering a half assed experience like that. If you are going to play the consumer friendly, open company then build consumer friendly products that work well!

September 16, 2011

Tutorials

It seems like everyone wants tutorials these days. In the last few days there have been many e-mails on the CXF users list looking for good tutorials. At FuseSource we keep getting asked for tutorials.
It makes sense in a lot of ways. Loads of people learn by doing and the best way to learn by doing is with a little guidance. Also, one way that a lot of code gets started is from the samples that ship with a development framework.
The trick is to write good tutorials. What makes a tutorial good? First and foremost, it should lead the reader to a successful outcome without frustrating them too much. A tutorial whose steps are set this environment variable and type mvn install is too easy and doesn't teach much. Not the other hand one that makes the reader type in tons of boiler plate code is too much bother. The reader should have to the core parts of work to learn the important bits. When they get it right, and they should easily get it right, it should work as expected.
A good tutorial should create something useful and close to real. HelloWorld doesn't quite cut it in a lot of cases. Even if the exercise is to simply show how to instantiate and publish a Web service, it would have more impact if the Web service did something. This may mean providing some implementation code along with the tutorial. If the goal of the tutorial is to implement something, make it interesting.
A good tutorial should be short. Short does not mean it must be easy. Short means it should be focused. A tutorial needs to show one thing. It can be simple like starting an ESB container or complex like using WS-RM or securing a Web service. But it should not focus on creating a secure and reliable Web service that runs in the ESB. If that is what you want to show, make it three tutorials that run into each other and provide code for readers who want to skip a head.
A good tutorial should also be authoritative and use best practices. While there are always, particularly with Apache projects, multiple ways to accomplish the same goal, a tutorial should only show the one the author, or his company, believes is the best practice for accomplishing the goal. New users like to be showed one way to do things. Once they get more experience they will discover other ways to approach a problem that may fit their specific needs better. The tutorial should, however, use an approach that will work in 99% of cases even if it is not the optimal solution for some.

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.