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.
