Say What You Mean

  • Article

The documentation tells you how to do something but not why you are doing it.

Haven't we all felt this way about documentation at one point in our software developer careers? It is a feeling not frequently voiced directly to writers; it lurks below the surface of other comments like:

  • I did this step but what did I just do?
  • I am ussing SSO to store passwords and other critical information, but why couldn't I just encrypt the stuff myself and use a custom component in my BizTalk Server application?
  • I cut-and-pasted a block of code from the SDK docs into my program and it works, but I am not quite sure why it works (or why I have to do it that way).
  • "You may see increased performance if you do one of the following..." Why can't the documentation make a definite suggestion?

This week I snuck over to the SOA conference and had the good fortune of overhearing a customer come right out and ask why the documentation did not include more of the "why" to go along with the ample amounts of "how". We need to get better at it. For example, the topic about BizTalk Server 2006 custom functoids [written by me] sez:

To make the functoid useful you must implement one or more methods depending upon the functoid category. If the functoid is cumulative, then you need to supply three methods—one for initialization, one to do the accumulation, and one to return the accumulated value. If the functoid is not cumulative, then you need to supply one method that returns a value.

This paragraph assumes you understand that a cumulative functoid cannot be implemented using a single method. If you stop and think about this, it makes perfect sense -- in the multi-threaded environment of the BizTalk mapping environment, you need one method to initiate the cumulation, one to bump/debump the value, and one to retrieve the value. You could hack this into a single method in your custom code, but in BizTalk, no dice. But is this backstory present in the docs? Not in the paragraph above. To be fair to the authur (*cough* me *cough*), this information is present in the parent topic, but it is sprinkled in among the meat and potatoes of method descriptions. It works, but only if you landed on the parent topic. So I could do better by adding a brief sentence of explanation.

The advice below follows:

You also have to decide if the functoid implementation code should be copied inline into the map or kept within a compiled .NET assembly and used through a reference.

Consider using an inline functoid when:

  • It is okay for others to read and potentially modify your business logic.
  • Your functoid depends only upon .NET Framework namespaces that the map supports. For available namespaces, see Scripting Using Inline C#, JScript .NET, and Visual Basic .NET.
  • You do not want to deploy and maintain another assembly with your BizTalk solution.
  • You are writing a series of functoids that share variables.

Consider using a referenced functoid when:

  • You do not want your business logic copied into the map where it might be seen or modified by others.
  • Your functoid depends upon .NET Framework classes that the map does not support.
  • The added functionality provided by the .NET Framework justifies deploying and maintaining another assembly with your BizTalk solution.

Ignoring the mush-word "consider", do these bullets answer "why"? I think they do. The documentation does not come right out and say "use a referenced functoid when you don't want your business logic copied..." but it does give the scenario. Is this enough?

Depending upon what the developer is trying to accomplish, his or her experience level, and the pressures of the project they are working on, the topic might be enough...or it might not. For me, sometimes I just want to be told the answer, sometimes I want to be told what to "consider". And while the functoid topic is more complete than not (remembering that I wrote it), other topics are not so clear especially when it comes to security and performance. The SDK samples are also guilty of briefly discussing the how, sometimes the why, and leaving the rest as an excercise for the reader.

There is a fine balance to strike. With your feedback, we can find it (or address specific topics you have a problem with -- it can be all about you!).