Best diagram/tool for documenting high-level architecture?

[James Lavery]

We have a customer who has asked us to document their systems starting at a high level and then drilling down into them.

They want the documentation to be diagrammatic rather than wordy (at the higher level at least).

Ideally they would like to have either a PDF or HTML diagram which can be drilled down into to navigate the detail of systems as they are discovered and documented.

Is EA suitable for this? I imagine so - I used it several years ago and know that it is very very capable.

If so, what diagram type is going to be best for this? Can we have drill-down in the generated diagrams (PDF or HTML or other)?

We want to get up and running fairly quickly, without (dare I say it), getting too hung up on methodologies etc! I think we only need the Professional edition (unless people advise differently).

I'd be interested in what people here can suggest.

Regards,

James

[Sunshine]

Yes you can do all that with Sparx Enterprise Architect.
Note the menu systems has changed to ribbons so it may be somewhat different to use than you remember a few years ago.

If you are getting down to software code and database tables level you could use the reverse engineering to speed things up too.
Most organisations I've been in tend to use the corporate edition as it supports DBMS as we have around 15 to 20 people using the same repository. With Professional edition there are limits on eapx/feap repositories which are based on MS Access and Firebird DB which may be okay if you have small numbers of people using the same repository. Have a look at the comparison matrix just to be sure what you need.

http://sparxsystems.com/products/ea/compare-editions.html

Of course the proof in the pudding is in the tasting, so before committing I suggest try downloading the 30 day trial edition and see if it meets your needs.

[Richard Freggi]

Yes Sparx is very well suited for this.
I recommend you read up on TOGAF Enterprise Continuum, TOGAF Enterprise and Strategic levels and/or Zachman Conceptual and Logical levels.  You will know what diagrams you need and how to present them to your customer.

Cheers

[Geert Bellekens]

I agree with about everything Sunshine just said.

Geert

[James Lavery]

Thanks for the feedback - all very useful.

At the risk of not conforming to the received wisdom with such things, is there a simple diagramming tool in EA which we can use to effectively free-draw a diagram of the systems (with drill-down), without adopting a specific methodology?

Ultimately we should and probably will use a formal architecture methodology, but initially we need simple, quick diagrams.

James

[qwerty]

Free drawing in EA is just nonsense (well, most of the times). You want objects with meaning to be modeled. Not just dumb scribble. Maybe you look into Archimate. To document existing architecture you can also go with simple components, ports and interfaces. Worked well for me.

q.

[James Lavery]

Free drawing in EA is just nonsense (well, most of the times). You want objects with meaning to be modeled. Not just dumb scribble. Maybe you look into Archimate. To document existing architecture you can also go with simple components, ports and interfaces. Worked well for me.

q.

Ha ha - I agree we don't want dumb scribble, and we want objects with meaning! I'm trying to get a balance between adopting an entire methodology to get some initially simple diagramming done.

When you say simple components, ports and interfaces, can you elaborate? Are you suggesting I can do this in EA or Archimate?

[Eamonn John Casey]

In our organisation we use Enterprise Architect to Draw the diagrams but use other Tools to expose those diagrams to others. This means the Learning curve for end-users does not include actual knowledge og Enterprise Architect (and licensing costs).

For example:
1. In a few lines of code you can run the HTMLReport to an IIS web site. Accessable for Confluence usage.
2. There are a few products (prolaterate? or something) that directly plug into EA Pro Cloud Server.
3. Sparx WebEA is also an alternative but there are SSO limitations which stop our organisation from rolling that out.

[qwerty]

You can use basic components from within EA. That#s basic EA (/UML) stuff and you easily get a sketch of an architecture. I don't have much experience with Archimate, but from what I saw it might be worth a close look.

q.

[Glassboy]

Ha ha - I agree we don't want dumb scribble, and we want objects with meaning! I'm trying to get a balance between adopting an entire methodology to get some initially simple diagramming done.

You can do what you want using about 4 UML shapes\connectors.  What you really need to do tho' is have a look at the TOGAF content meta-model.  The methodology is less important than having a structure to your content.

[Sunshine]

Methodology isn't necessarily bad but I know what you mean. However it is important to know what notation you want to use and that leads to the question regarding how much detail you want.
ArchiMate is really aimed at Enterprise Architecture level so its not good for detailed level. More like a black box notation where you don't care whats in the box. For instance the business objects and data objects don't have attributes.

UML is fine for getting down to the nitty gritty code and database levels. So more like white box where you do care whats in the box.

From what I interpret from

We have a customer who has asked us to document their systems starting at a high level and then drilling down into them.

It sounds like its down to detailed code and database tables and attributes so UML is probably the best choice. Note that the elements can be represented by graphics to make them more ascetically pleasing to the eye for certain stakeholders.

Done some similar models and my solution architects include things like this;

System [Package]
   Use Cases -  to describe what it does
   Components - to describe what its made up of
   Deployment Diagram - to show the components deployed onto servers
   Package and Class Diagrams - show the software architect and construction
   State Models - to describe any object states and events
   Interactions diagrams - to show any interactions at system/component/class levels

That usually covers what most people want. Haven't done any UML for around 11 years now so there might be some other stuff in the latest version of UML but the above works for us.

[qwerty]

Interstingly I interpreted the OP's question just the other way arounnd: get a rough picture of the architecture (so to decide what to do next). Probably his customer's goal should be clarified first.

q.