It has been a while, and now that I'm recommitting to this exercise, I want to share some thoughts about the experience. I've learned a couple of things about writing tutorials, especially step-by-step instructions for enterprise server applications.
The BizTalk Server 2006 end-to-end tutorials were:
- Tested as code multiple times by software test engineers.
- The first content in my division to go through Threat Model Assessment.
- Challenging, frustrating, fulfilling, a nightmare, an inspiration.
The tutorials continue to be broken. The comments and mail I've received through this blog continue to surface problems with Tutorial 3 in particular, and there is a recurring problem with the starter file for Tutorial 4. I'm beginning to feel jinxed. I know we've replaced the Tutorial 4 starter file a number of times, but the file distributed continues to be the wrong one.
A couple of lessons I've learned from this experience:
- Never, ever, ever put documentation support files in the \SDK folder of the product CD. The \SDK folder is sacred, and it makes PMs and developers too nervous to allow the documentation team to change and update our files as needed. In the future, we will deliver the files in our own folder.
- I am not anything like perfect. 400 pages of step-by-step instructions, deployment and configuration variations, etc., and there will always be errors. Even if the number of errors are significantly reduced, there will still be issues with user experience of the tutorials, and for every 'improvement', there is an equal and opposite problem introduced.
- Not all steps are equal. In an effort to provide information around complex steps, I ended up with a lot of lame content around not-so-complex steps in an effort to make all steps the same. I also missed differentiating between information that users only need to be told once with information that needed to be repeated. This led to the current constantly repeated reminders in almost every step: click to see controls! click to learn more about the tools!
Next Steps:
- I have 2 bugs open now, the first to make the updated tutorial support files available from the tutorial download page, and the second to fix the Tutorial 4 starter page. Hopefully both will be resolved soon.
- When I have the time I will republish the downloadable tutorial instructions. Various build problems have made this a very time consuming task. Some of the problems are supposed to be fixed now, and I'll find out if this is true or not. In the meanwhile, the most updated instructions are available in the BizTalk Server 2006 R2 documentation.
- I have a copy of the Tutorial 4 starter file that I manually fixed. It has not been thoroughly tested and officially checked in, but maybe it will help you today. I've attached a .ZIP containing the contents of C:\Tutorials\Lessons\BAS. (http://blogs.msdn.com/lizal/attachment/4173972.ashx)
