Apr 122007
 

know I know, I should sit back and bask in the fact that I have made a very good living understanding how BizTalk works and some of the neuances in the product are overcome. But I am not satisfied. I demand perfection!

Here are a list of some of the things that I think could be improved with how Microsoft documents and delivers their content to us mere mortals.

  1. More guts of the technical architecture of what goes on behind the scenes of their products. A case in point that I am intmately familiar with, the HIPAA database. There is very little documentation on what that database has in it, and how to leverage data that is contained in there. I have written an entry on how to extract the error information that is contained in it, but that was simply found by poking around. What is the purpose of the magic column in the parame table. What are all of the other columns used for? When you validate the schema in visual studio, there should be better documentation that states that it will invoke xsd2edi and compeif. How about some examples of MSMQT, what situations would you use them, and best of all: a few examples.
  2. What would be really nice is to have a section in the online help that would list of all of the hotfixes for that product. I think that having in online would be the best place, because then it would be up to date. I would appreciate a list so I don’t spend 3 days troubleshooting an issue only to call in and the helpdesk rep state “ya, that is a known issue, we have a hotfix for that.” I don’t care if it has not been fully tested, if it saves me working like crazy only to find out that someone else has reported it and there is a hotfix. Even if there is not a hotfix and it is an open item, I would like to know that they are working on it and I will gladly call up and have my name added to the list when the hotfix becomes available I will get it.
  3. I like whitepapers, but they seem to get published 2 years after the product is out. A little too late for me… …about 2 years too late! Why can’t whitepapers be released as soon as the product is released? In order to qualify for a Beta program, you have share your experiences with the product, why can’t a whitepaper be required for Beta customers?
  4. Another irk I have is with some of BizTalk pieces. With all of the troubleshooting contained in Visual Studio, why can’t more of it be integrated for BizTalk? The pipeline testing components in the SDK, why not are they part of the VS enviornment? A test enviornment that can be invoked from within VS to test an orchestration instead of having to deploy it and ‘test’ it there? Visual Studio has the ability to create test scenarios for C# methods, it would be possible to emulate an enviorment in VS for orchestrations, right click and choose Setup, and supply sources for data and file drop locations for outbound data (the ability to read and drop in both XML and flat file structures). Also if responses are not yet available, the ability from within the Setup dialog box to auto generate responses based on the schemas.
  5. There are some best practices designs already published, convoy processing, for example. Why can’t I go online from Microsoft and download a template that gets me started, so it is part of the templates? (does it exist already?) Maybe sections in the templates section, B2B, A2A, etc.
  6. I am a picture guy, I like the pictures that used to be there in the docs online, now they are gone. Examples of the different uses of the functiods for example.
  7. I would like a better search by product feature on the msdn site. I read that it normally takes 7 clicks to find what you are looking for, and it is especially true, if not worse on the MSDN site. Can’t MS afford to buy some brainiacs away from Google to improve the hit ratio for their own site?
  8. There are a lot of great blogs from MS guys, who have more access to how things really work behind the scenes. Why can’t their blog entries be included in the documentation. Keith Lim and Kevin Lam are great examples, if I am reading about BAM, it would be great to have a link from within the documenation right to his blog, or simply having his blog become part of documentaion. If I want to understand about port definitions Kevin’s blog is a perfect place to end up. But I would NEVER know that by reading documentation.
  9. The examples in the SDK (at least in BizTalk) have very little documentation on what it is going to do, and why it is doing it. When all I can see is how to set it up.

To list a few things that I think are good, so this is not simply a rant:

  1. The SQL Server books online are pretty comprehensive. If all documentation was as thorough as SQL Server there would be less conflict in the world.
  2. Readability. The documentation is usually clear and concise.

Use this reply section to add your thoughts!

  • Dave Shank

    Eric, I am the group manager for the SQL Server documentation team and wanted to first thank you for noting the quality of our work – we try very hard to get this right and it is great when our customers notice. Second, your list of areas where we can do better is well thoughtful and right on the money. Many of these are areas of improvement already int he works. Some of your issues are owned by other doc teams (biztalk for example) and so I have no control over them. I do know the BizTalk team however and know that they are really working hard to make improvements. I’d share your feedback with that team as well.

    Thanks for the info and feedback.

  • Good points. Re: the templates, have you looked at Jon Flanders Pattern Wizards? They are just what you have asked for !! I agree that the tools should be more integrated into VS. It would be nice if we could have things like Tomas Restrepos Pipeline Tester as an add-in or we could just right click a pipeline class and say “generate tests”. Im looking at doing something like this with my BizUnitExtensions project on codeplex- i’ll let you know if i make some good progress on that …

    cheers
    benjy