Win a copy of Pro Spring MVC with WebFlux: Web Development in Spring Framework 5 and Spring Boot 2 this week in the Spring forum!
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Ron McLeod
  • Paul Clapham
  • Jeanne Boyarsky
  • Liutauras Vilda
Sheriffs:
  • Rob Spoor
  • Bear Bibeault
  • Tim Cooke
Saloon Keepers:
  • Tim Moores
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Piet Souris
Bartenders:
  • Frits Walraven
  • Himai Minh

Part 2: "self-contained" diagrams ?

 
Ranch Hand
Posts: 183
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
 
Greenhorn
Posts: 18
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I personaly think some notes on diagram itself and a good description in word document (after Assumptions section maybe) would be good enough.
 
Ranch Hand
Posts: 254
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.
 
Greenhorn
Posts: 11
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Ranch Hand
Posts: 254
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

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
Greenhorn
Posts: 11
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Let me re·phrase the question..
Can the supported documentation be submitted as "word document"?
 
J J Wright
Ranch Hand
Posts: 254
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.
 
Ranch Hand
Posts: 42
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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?
 
You showed up just in time for the waffles! And this tiny ad:
Building a Better World in your Backyard by Paul Wheaton and Shawn Klassen-Koop
https://coderanch.com/wiki/718759/books/Building-World-Backyard-Paul-Wheaton
reply
    Bookmark Topic Watch Topic
  • New Topic