how verbose should be design desision document?

[Svetlana Koshkina]

I am writing my design desisions doc and got very tired: it is already more than 7 pages of text.
How long is too long? What do you, guys, think?

[Andrew Monkhouse]

Hi Svetlana

How do we know our assignment is ready to be submitted?

When we are really sick of working on it.

Billy Tsai also asked about how many pages to write. Since no-one else responded, I wont direct you to that thread, but here was my response:

I normally do not care about counting lines of code, or numbers of classes, or numbers of pages of documentation. To me: once the documentation is clear, it is complete. I don't care if it is twice as many pages as someone else, or half the pages of someone else. The exception of course, is when writing something that has a fixed word limit.
However since you asked, I will try and count them
[andrewm@andrewm scjd]$ wc -l README.txt
414 README.txt
[andrewm@andrewm scjd]$ echo $((414/66))
6
So, assuming 66 lines per page, we get 6 pages for my README.txt file.
My DesignChoices.html file was in html format (we were allowed this in the old assignment). Loading that into my word processor shows 11 pages.
My user documentation totalled 19 pages (roughly 2 pages for each major screen, plus additional pages for modules as a whole). Also in html format.
By the way, I am constantly accused of writing too much (just look at how long any of my posts are )

This was not counting my class diagrams which made up another 4 pages.
One of the things I enjoyed about participating in this forum was that it helped highlight a few design decisions I had made where I hadnt been consciously aware of making a decision. Quite often someone would post a question, and in answering it, I would realise that there were choices I had subconsciously rejected. This gave me more things to put in my design choices.
Regards, Andrew
[ July 12, 2003: Message edited by: Andrew Monkhouse ]

[Svetlana Koshkina]

I see, mine is going to be about the same. It actually what i wanted to know. Thanks a lot.
My application is actually complete. There is nothing to be improved at this point. Only i will need to clear one constant customer that had reserved a lot of tickets and owes to Fly By Nite company more than $209,000. I caught couple of flees for last two days though, that's all. I want it to come to the end, beeee-dly.
Did your design desisions writing help you to write amswers on written exam quicker and easier?

[Andrew Monkhouse]

Hi Svetlana

Did your design desisions writing help you to write amswers on written exam quicker and easier?

I think so. There were no questions in the exam that I had not already discussed in my design decisions document, so all I had to do was write down the same points again.
Regards, Andrew

[Patrick Cobbett]

Hi Svetlana and Andrew,
yes Andrew your posts ARE informatively long!
Having written what i thought was a long design decisions document(although not anything like as long as yours is!), and had reservations about it.. so.. i posed the same question directly to Sun
My email asked:

I have a small query regarding my submission for the Java Developer's assignment. The assignment specifies that the submission should include a design decision justifications document. How much is appropriate to write for this? I considered writing more than less to be on the safe side, however i do not wish to write more than is appropriate, or less for that matter. Can i be given a clue as to how many words is typically expected. How much should be written for each design decision documented?
>Finally, this question also applies to the user documentation (not the readme.txt file).
>
> Thanks for your time

They responded with:

Don't go overboard on this. We're just looking for something simple ... a few sentences on each major decision.

So, it appears that on the contrary they aren't looking for too much here. It would be harsh if they penalised you for writing too much. I just wanted to keep the examiner sweet

[Svetlana Koshkina]

Thank you guys, it was very valuable information.
Interestingly, I like my program even better, since I started writing down design desisions
So clever! So many major desisions and so little design... One line per every desision and it grows into something short of a manuscript. Oh God, make it stop!

[Svetlana Koshkina]

I was wondering when i stop writing desisios with 's'.

[Jim Yingst]

One line per every desision and it grows into something short of a manuscript. Oh God, make it stop!

I suspect my own design doc will grow similarly if I'm not careful. I'll have to try to restrain myself.

[Lucy Sommerman]

hmm..so we can safely assume that my page and a half is woefully inadequate... o well we will just have to see how it goes...and the exam just asks you to justify the decisions you made, right, explain RMI, etc...

[Andrew Monkhouse]

Originally posted by Lucy Sommerman:
hmm..so we can safely assume that my page and a half is woefully inadequate...

No, you can safely assume that I (and others) dont know when to stop.

In reality, Sun are only interested in major design decisions - and you only need to write one or two bullet points for each of them. So you could probably get away with less than a page's worth.

Regards, Andrew

[Anton Golovin]

If you can read what you write, and it seems clear to you, and it gives an overview of your major design decisions, I would say it is good enough.