• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Need some help on documentation

 
Dhiren Joshi
Ranch Hand
Posts: 463
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I want some help in understanding what we need to write when we are justifying design decisions.
Is it justifying the patterns, the introduction of new classes, or general interaction of sequence diagram needs explaination to clarify it further.
Should the justification explaination be such that it should be explained such that a developer who is looking at it from implementation stand point can grasp the lower level concepts.
I dont want to put too much together and I dont want to leave too much out.
Can some one please help.

Thanks
Dhiren
 
Yong How, Lim
Ranch Hand
Posts: 52
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Dhiren,

By definition patterns are there to be understand and to be used,
as a common body of knowledge
so in that sense you should not need to justify patterns.

You might need to justify the use of patterns especially it is not obvious.
IMHO, you do not need to justify or explain the sequence diagram if you have put in sufficient labelling and remarks.

The general rule should be this :
Specify what and why it is so, but not HOW.

HTH

Regards,
Yong How, Lim
SCEA, SCJD, SCJP
 
Dhiren Joshi
Ranch Hand
Posts: 463
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Yong,
Thanks for the information.
with the what and why, Is it necessary to explain something as common as the usage of composite entity bean.
Some parts of the pattern usage like u said are common body of knowledge which accomplish a known functionality so it becomes confusing which aspect of my implementation would require justification which wouldnt.

For example .. Why I used a composite entity instead of a POJO .. Does that qualify for an explaination. ?


Thanks
Dhiren
 
Deepak Pant
Ranch Hand
Posts: 446
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Dhiren,

I just submitted my assignment few days back.

I am not sure how it gets evaluated but here is what I did:

(a) Added a list of assumptions (technical / non-technical)
- non-technical assumptions to cover or clear out functional confusions.
- technical ones to clear why I took a particular approach

(b) Provided a reference of all the books/design patterns/websites I referenced while coming up with the solution. So I did not explain the design patterns. I just mentioned the list of patterns.

(c) Links to all the diagrams (component, class, sequence)

Hope this helps

Deepak
 
Josep Andreas
Ranch Hand
Posts: 90
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Dhiren,
I want to upload the assignment by the end of the weekend.
So I am also busy with the documentation.

In the requirements they only ask a list with assumptions.
So i think If you submit anything more you should keep it
short and clear.

So i don't think a explanation is required where you evaluate all
options that are available with all cons and pros and
then come to your conclusion. I do think this would be too much.

I think a design decision might look like this:
copied from petstore:
SFSB is used because
"
1. Thread safety
2. Lifecycle management
3. Client type Neutral
4. Scalable
"

I will do the following:
0. A list with links to all paragraphs
1. A list with assumptions
2. I list with design decisions. (e.g explain why you used SFSB)
3. Scope
4. Add some appendixes (could be: 1 definitions used; 2. List with JSPs + function; 3. List with Classes+function; 4. Patterns uses; 5. something about each element in QoS requirements)

I think this will make the document easy to navigate.
probably the grader will be most interested in:
- assumptions
- design decisions
- Qos
- Patterns Used

what do you think?
Am I missing something important?
 
Josep Andreas
Ranch Hand
Posts: 90
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Oops.. Don't forget to include the diagrams
 
Yong How, Lim
Ranch Hand
Posts: 52
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
When we are digging deep and getting our hands dirty,
we tends to forget the most important thing, satisfying the requirements.
Whatever we do, it does not matter if we use POJO or Composite Entity,
any project can only be labelled as completed and successful if our design can satify the requirements using the most appropriate technology.

So as long as your design can satisfy the requirements of the SCEA project,
and you can justify it is most appropriate, then you will do no wrong.
 
Josep Andreas
Ranch Hand
Posts: 90
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Yong How,
your right (of course).
Only for this project the most important requirement is "J2EE". Doesn't this mean that at least to some extend you shoul get your hands dirty?

Could you be more specific?
regards,
j
 
Josep Andreas
Ranch Hand
Posts: 90
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Dhiren,
I am using this URL as a template for my design:
http://java.sun.com/blueprints/code/adventure/1.0/docs/architecture.html

It's a little bit too long, but I think the various paragraphs are OK and I think this will be more or less what SUN might expect of the document.

regards,J
 
Yong How, Lim
Ranch Hand
Posts: 52
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Josep,

I do not quite understand your question.

Of course using J2EE in this assignment is a MUST,
but dont forget that ALL requirement is important to the user.

What I am trying to say earlier is that while trying to design a architectural design for the client, we must never forget why we are doing this. It does not matter how wonderful or how advance you design is, but when it does not FULLY satify the ALL the requirements, the client will consider the design as crappy.

Back to basic... Satifsy FULLY ALL the requirement.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic