(See here for
the current version of the naming conventions!)

One of the primary benefits of the BizTalk Orchestration model is the great transparency
you can get when a software implementation is pictorial.

Regardless of how well a developer comments code, there will always be a need
to maintain a separate set of artifacts (UML diagrams, Visio diagrams with random
shapes of your choosing, prose documents, whiteboard discussions, etc.) that are used
to convey what the code is actually doing especially when working with a business
audience.  This is true if for no other reason than that a discussion of interesting
functionality will often take place at a different level of granularity than raw code
can support

Round-trip engineering tools – that attempt to keep code in sync with diagrams often
seem to suffer from a lack of fidelity that renders them ineffective.

With BizTalk Orchestration, the diagram is the implementation (at least at
a particular level) of a piece of functionality.  Yes, you can disappear into
components and lose sight of what might happen.  Yes, there is a code representation
(xlang/s) underneath the orchestration but it seems to be completely isomorphic with
the diagram.

So the opportunity exists to use an orchestration diagram in several interesting ways
within a project lifecycle:

  1. As a way to capture an initial high-level design, using all the orchestration shapes
    as intended but not yet bothering with real maps and schemas.  Stubbing out schemas
    (so you can declare messages and variables to be of proper types) and maps will allow
    you to flesh out the orchestration diagram(s) quite a bit, using the compiler as just
    a way to check for consistency.  All of the external system interactions, communication
    patterns, decision points, parallel vs. joined flows, etc. can be represented at this
    point in a shell orchestration.

  2. As a way to gain consensus with the development team & business sponsor about
    whether the right functionality is indeed going to be built.  The high level
    design just described is a great tool for this discussion.  Put your orchestration(s)
    up on a wall with a projector and do a walk-through with as many of the project stakeholders
    as makes sense.  Or use a tool like CutePDF to
    print the orchestration as a PDF to send around via email.  (Of course, once
    Microsoft ships the Visio add-on for BizTalk 2004 orchestrations, this will represent
    another option for non-VS.NET users.  This has the added benefit of allowing
    you to exclude what you might consider to be lower-level detail by setting the Report
    to Analyst switch on various orchestration shapes to False.)

  3. As a way to estimate work.  The various shapes in your initial orchestration
    can often represent reasonable granularity for time estimates.

  4. And finally, as a way to guide project work…Rather than starting with the entire
    orchestration that you created to support steps 1-3, you might find it easier to create
    a new orchestration that represents the path(s) you are tackling at a particular point. 
    You can cut/paste portions of that original orchestration or simply use it as a reference
    for what comes next it serves as your outline.

To help realize some of these benefits, naming conventions within an orchestration
are quite important

While the naming conventions are good practice for variables, Messages, Multi-Part
types, etc. they are even more import for the workflow shapes.  The goal is to
ensure that the intent of each shape is clear, and that the text associated with the
shape conveys as much as possible given the space constraints.  In this way,
a non-technical audience will be able to use the orchestration as documentation.

(See here for
the current version of the naming conventions.)

Respond with comments & the document will remain updated per your feedback!