Part 2: "self-contained" diagrams ?

[Benoît de Chateauvieux]

Hi All,

When writing my Software Architecture Documentation, I generally use this template.

It contains an element catalog for every diagram where one can add a description for:
- Components and Properties
- Relationship and Properties
- Components Interface
and Rationale.

Do you think it's a good idea to include it in the submission or must be the diagrams "self-contained" ?

Thanks for your help,

Benoît

[James Owen]

I personaly think some notes on diagram itself and a good description in word document (after Assumptions section maybe) would be good enough.

[J J Wright]

By self contained I take it you mean the diagram alone should contain all the information necessary to move from design to implementation.

I don't think this is realistic. I see nothing wrong with providing supplementary documentation to support diagram elements. For example, notes on your diagram may link to an expanded explanation in your supplementary documentation. Adding verbose notes to a diagram does nothing for it's readability.

Also, if you look at processes like RUP, there's more to Analysis and Design than simply producing a Design Model. The template your proposing seems to be along the lines of a RUP Software Architecture Document, so I think it's fine to include it. You won't get extra marks for it, but if it helps the examiner understand your design it can't be bad. Just make sure it's not an excuse to produce poor diagrams.

[Rajashekar Akula]

I have a question regarding the documentation part of the assignment submission -
The deliverables part of the assignment says that "all the deliverables will be accepted as HTMLs only".
Risk list and supporting documentation(assumptions, decisions etc.,) should be included in htmls only OR we can include in word document and provide links from HTML.

Thanks in advance,

Raj

[J J Wright]

The deliverables part of the assignment says that "all the deliverables will be accepted as HTMLs only".

Where's the ambiguity in that?

[Rajashekar Akula]

Let me re·phrase the question..
Can the supported documentation be submitted as "word document"?

[J J Wright]

OK, if the ambiguity is based on whether or not supporting documentation is classified as a deliverable. I would most definitely err on the side of caution. My understanding of the word deliverable includes any work product, regardless of whether it's required or supporting. Besides I don't see any reason to separate the two. What would be the motivation for sending your work in two different formats?

From Sun's perspective there are undoubtedly very good reasons for only accepting HTML, i.e. it's ubiquitous and doesn't contain macro viruses. If you take the line that it's OK to send supporting documentation in Word format, then what about every other document format? Where do you draw the line?

If after all that you still feel strongly about sending your supporting documentation in a format other than HTML then at least it send it in non-proprietary format, e.g. OpenDocument Format.

[Unnikrishnan Nair]

I feel it is not good to send any other formats than what Sun explicitly mentioned. Created HTML pages with the design components added as images with few write ups should resolve your issue. Why do you think you need a word doc?