Re: Summary of findings of TA Spec. review. my 2c

[Krishna Sankar <ksankar@cisco.com>]

Hi all,

	I agree with Duane in that the Architecture specification *is* important
and is the foundation. So we do need one at Tokyo. We are software
professionals - we live and die by architecture.

	As there are a lot of e-mails and some concerns, I dedicated this Sunday to
analyze this document (to the best I can). Here are some of my comments:

1.	Nagwa & Tim are referring to the version 0.8.71. I do not think they are
referring to an old document. Is this the current version ?

2.	I do have to agree with Nagwa and Tim in the sense that this document
does *not* read like an architecture document. But as I read thru the
document, it has a lot of information. The team has done a lot of work and
it shows. But the document needs reorganization and more material/diagrams
for a lot of sections.

3.	For example, the first detailed section should be the one which describes
the ebXML architecture - what are the components at a high level, how do
they fit in - some are layers like the business processes run on the
transport and some are orthogonal like the regrep. Some are implementations,
some are concepts like the BP/CC, .... you get the picture.

	For e.g.: Line 210: Talks about seven components. We should define these
and give a brief description in 3.0. Something like "the ebXML Architecture
is based on seven components viz. ..."

4.	We need a lot of diagrams explaining the ebXML Architecture - the systems
overview diagram is over used; it is there everywhere. Even though a common
diagram shows consistency, having only the common diagram does not explain
much. The architecture diagram has to elaborate on this common vision with
more text and diagrams.

5.	Many sections do not have a theme or worst some have multiple themes.
Each section should do only one thing and it should do it well. (I have
heard this many times from my books' editors - sometimes in not so
flattering words !)

6.	The Section 5 road map should be an Appendix. As it stands now, we are
describing a roadmap without even covering what the components are.

7.	Yes, the document has a regrep-centric feel. It is because a lot of the
sections talk only or talk much more about the regrep. We do need to take
some stuff off and add more from other components point of view.

8.	The use cases are good. But we need to add more. Things like the
discovery, how to bootstrap a communication, etc are missing. I think if we
look at each components and capture the most important use cases we should
have them all.

	Detailed and more elaborate use cases do belong to the respective
specifications. I am not sure about your point in the case of regrep.

9.	The use cases do need a taxonomy/categorization. Now it looks like a list
of use cases without any relationship.

	A diagram showing their relationships would help. The diagram can also have
the 7 major components in the Y axis thus showing where each use case fits
in. (I can draw a strawperson diagram)

10.	The sample files section is good. It needs a new name - may be sample
documents is better or something much more generic. Here we run the
dichotomy problem. This document needs to be revised every time a new
sub-document comes out else this section will be outdated.

	On second thought, the examples would not make sense without the sub
documents anyway.

11.	We do need a lot of sequence diagrams explaining the various concepts,
interactions et al. Many of them belong in the use case section.

12.	That brings me to the use case section - do we need one ? It is good, in
the sense that it describes what a minimum system should have. But it adds
pages to the document and complexity.

	I think if we judiciously select use cases which amplify the ebXML
architecture and explain the end-to-end process, develop good sequence
diagrams and elaborate the relationships among the use cases, this section
would do justice.

13.	We do need a section for various "shalls" and assumptions.

	Now that I am an accessory ;-), I offer any help needed for all of us to
get a good document out by Tokyo. As Duane said, with out an Architecture
document, we cannot have the other documents.

	cheers and have a nice weekend
----------------------------------------------------------
       |          |             Krishna Sankar
      :|:        :|:            Member of technical Staff
     :|||:      :|||:           Internet Commerce
 ..:|||||||:..:|||||||:..       (Ph) 408-853-8475
    Cisco  Systems Inc          ksankar@cisco.com
----------------------------------------------------------
"Failure is certain if we don't,
           but Success is uncertain even when we do.
                         So the choice is Ours, always..."
----------------------------------------------------------