Ongoing documentation of SOA

[Michelle]

Hi...

Please forgive the slightly less than focussed post, but I couldn't find
another place to post this question... this is an open question to people
who do software and/or Enterprise Architecture.

I think I'm new to SOA and architecture-- but I seem to have been doing it
for a while. I'm wondering how a person should be documenting ongoing
changes to your architecture. I mean, it's pretty easy for someone in an
organization to slap a new web service somewhere, but how are these kinds of
things getting documented?

Obviously, this could get pretty intense-- citing references that I should
read would be equally helpful to posting your opinions. But I'm looking for
the big and small picture-- eg: real-world considerations that are crucial,
politics to be aware of, risks... that sort of stuff.

Thanks,
M

[Claus Konrad [MCSD]]

A very broad question indeed.
Depends on the size of the organization, but most likely (normally) the
it-department responsible of keeping the productionsystems airborne, would
keep track of what services/application are installed on which IP-addresses,
port etc.

No one should be allowed to host a webservice to the "world"
(internally/externally) and expect it to be catered for by IT-support; if
this has not been discussed with IT.

How to document?
Well - visio is an often used "tool" for this. In addition, some commercial
products exist AFAIK capable to produce diagrams of known applications.
--
rgds.
/Claus Konrad
MCSD.NET (C#)
"Michelle" wrote:

Hi...

Please forgive the slightly less than focussed post, but I couldn't find
another place to post this question... this is an open question to people
who do software and/or Enterprise Architecture.

I think I'm new to SOA and architecture-- but I seem to have been doing it
for a while. I'm wondering how a person should be documenting ongoing
changes to your architecture. I mean, it's pretty easy for someone in an
organization to slap a new web service somewhere, but how are these kinds of
things getting documented?

Obviously, this could get pretty intense-- citing references that I should
read would be equally helpful to posting your opinions. But I'm looking for
the big and small picture-- eg: real-world considerations that are crucial,
politics to be aware of, risks... that sort of stuff.

Thanks,
M

[kferron]

I just want to add that while code documentation can be a crucial
mechanism for retaining value with intellectual property, one of the
things that a standardized discovery model like the web services
provides, is exactly that.. the ability for consumers to discover not
only what the services are in a given location (UDDI can help organize
that canonization), but also for consumers to discover the "how" of the
service.
On Nov 14, 4:33 pm, Claus Konrad [MCSD]
<[e-mail]:

A very broad question indeed.
Depends on the size of the organization, but most likely (normally) the
it-department responsible of keeping the productionsystems airborne, would
keep track of what services/application are installed on which IP-addresses,
port etc.

No one should be allowed to host a webservice to the "world"
(internally/externally) and expect it to be catered for by IT-support; if
this has not been discussed with IT.

How to document?
Well - visio is an often used "tool" for this. In addition, some commercial
products exist AFAIK capable to produce diagrams of known applications.

--
rgds.
/Claus Konrad
MCSD.NET (C#)

"Michelle" wrote:

Hi...

Please forgive the slightly less than focussed post, but I couldn't find
another place to post this question... this is an open question to people
who do software and/or Enterprise Architecture.

I think I'm new to SOA and architecture-- but I seem to have been doing it
for a while. I'm wondering how a person should be documenting ongoing
changes to your architecture. I mean, it's pretty easy for someone in an
organization to slap a new web service somewhere, but how are these kinds of
things getting documented?

Obviously, this could get pretty intense-- citing references that I should
read would be equally helpful to posting your opinions. But I'm looking for
the big and small picture-- eg: real-world considerations that are crucial,
politics to be aware of, risks... that sort of stuff.

Thanks,
M- Hide quoted text -- Show quoted text -

[Michelle]

Ok, so once we've documented our code, and drawn some Visio diagrams, what
then?... I guess I need to know what form a company's documentation of these
things should take... for example, do I put these diagrams in a binder? Are
there templates for other documents that we should be using?

Thanks,
Michelle

"kferron" <ke**********@gmail.comwrote in message
news:11**********************@h48g2000cwc.googlegr oups.com...

>
I just want to add that while code documentation can be a crucial
mechanism for retaining value with intellectual property, one of the
things that a standardized discovery model like the web services
provides, is exactly that.. the ability for consumers to discover not
only what the services are in a given location (UDDI can help organize
that canonization), but also for consumers to discover the "how" of the
service.
On Nov 14, 4:33 pm, Claus Konrad [MCSD]
<[e-mail]:

>A very broad question indeed.
Depends on the size of the organization, but most likely (normally) the
it-department responsible of keeping the productionsystems airborne,
would
keep track of what services/application are installed on which
IP-addresses,
port etc.

No one should be allowed to host a webservice to the "world"
(internally/externally) and expect it to be catered for by IT-support; if
this has not been discussed with IT.

How to document?
Well - visio is an often used "tool" for this. In addition, some
commercial
products exist AFAIK capable to produce diagrams of known applications.

--
rgds.
/Claus Konrad
MCSD.NET (C#)

"Michelle" wrote:

Hi...

Please forgive the slightly less than focussed post, but I couldn't
find
another place to post this question... this is an open question to
people
who do software and/or Enterprise Architecture.

I think I'm new to SOA and architecture-- but I seem to have been doing
it
for a while. I'm wondering how a person should be documenting ongoing
changes to your architecture. I mean, it's pretty easy for someone in
an
organization to slap a new web service somewhere, but how are these
kinds of
things getting documented?

Obviously, this could get pretty intense-- citing references that I
should
read would be equally helpful to posting your opinions. But I'm
looking for
the big and small picture-- eg: real-world considerations that are
crucial,
politics to be aware of, risks... that sort of stuff.

Thanks,
M- Hide quoted text -- Show quoted text -