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.


  1. I've been using Camel and other fuse products for a few years now and I have also been trying to get other software engineers to use the products as well. Here are some of the issues I have faced over the years when trying to push fuse's products into new developers:

    1) The documentation for the products is spread over many websites, this is confusing for new and first time developers. For example, some documentation on the fuse site is not. It would be nice to have all the documentation accessible from a single location.

    2) Many of the software engineers I have been pushing to use products such as camel sometimes have very little Java coding experience and thus, have no Spring or Maven experience either. One of my colleagues explained to me when he was reading the camel book that there was way too much focus on spring (including the code examples). For first time developers this is very intimidating. If new developers just want to learn camel they shouldn't be forced to learn maven and spring as well. Ideally examples should be provided in both Java DSL and spring.

  2. FuseSource is constantly working to improve the documentation and will begin mirroring the Apache content on our site in a few months.
    I whole heartedly agree that some of the projects are too hard for non-experts! There is a Fuse IDE that abstracts a lot of the Spring and Maven stuff so the developer doesn't have to know about it. The IDE also has a drag an drop route editor that makes it easy to create routes.