• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Format of the Design Decisions document

 
Ian Roberts
Ranch Hand
Posts: 46
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
All,
Has anyone successfully submitted a design decisions document in a Microsoft Word format? Sun don't actually say what the format must be but state that the Readme must be in simple text.
Cheers,
 
Ken Krebs
Ranch Hand
Posts: 451
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Ian,
I wouldn't go there if I were you, it's begging for trouble. Are you sure there's nothing about the format in your instructions ???
Regarding the design document, my instructions said :
A file called choices.txt. This must contain pure ASCII(not a word processor format) text ...
 
Ian Roberts
Ranch Hand
Posts: 46
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I've double checked my instructions and it only refers to the Readme file being in text format. The Design Choices document does not have a specific format stated.
Does anyone else know of a submission using MS Word?
What could be a solution is to present a Design Choices document in text, without UML diagrams, and another in Word with UML diagrams. The ReadMe text file can give the assessor the choice.
I understand what you are saying and I think I need to supply a text version regardless but I may also include it again in Word format.
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Ian,
Originally posted by Ian Roberts:
I've double checked my instructions and it only refers to the Readme file being in text format. The Design Choices document does not have a specific format stated.
Does anyone else know of a submission using MS Word?
What could be a solution is to present a Design Choices document in text, without UML diagrams, and another in Word with UML diagrams. The ReadMe text file can give the assessor the choice.
I understand what you are saying and I think I need to supply a text version regardless but I may also include it again in Word format.

As long as you are providing a design choices document in text format you should be OK. I think the reason for the restriction in some of the newer assignments (although apparently not in yours) is that with the restriction the examiner doesn't have to have Word (or WordPerfect, or whichever word processor you choose to use) in order to evaluate your assignment. I suspect it's possible the examiner who receives your assignment will not have Word installed and will probably not loose any sleep over the fact that he can't see the Word formatted version of your design choices document.
In my opinion, including UML diagrams in the design choices document is not required, that is, it is beyond the scope of the assignment. If you want to make certain that the examiner sees your UML diagrams you could include them in the text version (I know it's not going to look the same as it would in Word).
 
Seid Myadiyev
Ranch Hand
Posts: 196
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hello Ian, Ken and George,
I just would like to add that my instructions document allows HTML format for user documentation, and this is where the UML diagrams could go, perhaps under a separate section for technical information.
Thank you.
Seid
 
Ian Roberts
Ranch Hand
Posts: 46
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
George,
I have to agree with you. Although my assignment may not state the Design Choices document to be in text format the fact that later versions do is worrying. To be on the safe side I may include a suggested UML Reference document and state in the Design Choices document that it can be viewed using MS Word. That way, the Design Choices document is in simple text but a reference document (additional information) can be viewed using a word processor.
Although in this assignment the assessors do not expect to see UML documentation, I stongly believe that the assignment should require UML documentation as this is something a developer should be able to present sufficient knowledge upon. The IBM developer certification does require a UML test, although I believe it is not very difficult (or so I'm told by someone who has passed it!).
In a commercial environment, I wouldn't dream of delivering a Design Choices document without graphical representations (in UML) supplementing my reasons - but my job role is a J2EE designer/architect and therefore I'm a little more focused upon presenting the solutions in documentation and code.
However, I do agree with you. In this context it is not a requirement - why I'm not sure as there is more to be a developer than delivering JAR files.
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Ian,
I agree with you that UML documentation probably should be required in some future version of the SCJD. However, it's not required for the current assignment and on that basis I think it's beyond the scope of the project (as it exists now). I think you're wise to provide the Design Choices document in text format (even if your instructions don't have this restriction) because it does make things easier for the examiner. No one is going to complain if you provide UML documentation. While I don't think you will get extra points for doing so, it certainly won't hurt your grade. If you think it's important to do so and it doesn't contradict anything in your assignment instructions, well then, why not? I encourage people to do whatever they feel is important for their project. I think there's a natural tendency to go beyond the scope of the project on the part of many SCJD candidates (I was guilty of this myself) and provide things that are not really required or expected. So when I see someone propose something that I think exceeds the requirements I try to point that out. But, of course, it's your decision and it's important for you to do what you think is right. It's your project after all.
 
Andrew Monkhouse
author and jackaroo
Marshal Commander
Pie
Posts: 12014
220
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Ian & George,
I doubt that Sun will require SCJD candidates to create UML diagrams. The SCEA assignment is basically creating UML diagrams from vague instructions. So it appears that Sun see this as being an architects job, not a developers job.
Having said that, I did create UML diagrams for my SCJD assignment, and I submitted them as HTML files. I just provided a link to them in my design decisions document in case the examiner wanted to see them.
Regards, Andrew
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic