Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

How to better structure the choices document?

 
alzamabar
Ranch Hand
Posts: 379
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi, I would like to hear from your experience the best way you used to create the choice document.
On one side, we need to document **each** choice; on the other we should also give reasons for our general design decisions. The two kind of info are at different level: one is at a class level, the other is at from a more general point of view.
I was thinking of documenting the general choices at the beginning, in a colloquial way, and then create sections for each class, where I explain why some decisions have been taken.
What do you think of this approach?
Thanks,
Marco
 
Nicholas Cheung
Ranch Hand
Posts: 4982
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
It is difficult to say, since different people have different writing style.
I just show up the TOC of my documentation, and I hope this helps you to make up your mind.

[1] Overview
[2] General Considerations and Assumptions
[3] Server Design
[4] Client Design
[5] Record Locking Mechanism
[6] Record Searching Mechanism
[7] Networking Approach
[8] Major Design Patterns Applied
[9] Data Model used for displaying data in JTable
[10] Exception Handling and logging
[11] Thread Safety
[12] Flexibility for further extension
[13] Javadoc documentation
[14] Package Structure for submission

I got my ideas from Andrew and Mark in fact, they have guided me for the documentations when I worked on this assignment, I hope this helps you.
Although it looks like quite details, I think it is also useful for you to prepare the essay exams.
Honestly, the essay exam questions are based on your design, so, the more you write and think, the easier you answer the questions.
Best wishes for your SCJD.
Nick
 
alzamabar
Ranch Hand
Posts: 379
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Nicholas,
thank you for that. It helped considerably also, as you said, in focusing on the key points of the assessment.
I think I'll go for an HTML document.
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Marco,
Originally posted by Marco Tedone:
I think I'll go for an HTML document.

You might want to check your assignment instructions regarding the format of the design choices document. My assignment instructions state:

A file called choices.txt that containing pure ASCII (not a word processor format) text describing the significant design choices you made. Detail the problems you perceived, the issues surrounding them, your value judgments, and the decisions that you made. This document should also describe any uncertainties you had regarding the project, and the decisions you made when resolving them.

which I understood to prohibit me from using an HTML format.
[ March 24, 2004: Message edited by: George Marinkovich ]
 
alzamabar
Ranch Hand
Posts: 379
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi George,
Originally posted by George Marinkovich:
Hi Marco,

which I understood to prohibit me from using an HTML format.
[ March 24, 2004: Message edited by: George Marinkovich ]

it's the same for me. I cannot use the HTML for this particular document.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic