• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

how verbose should be design desision document?

 
Svetlana Koshkina
Ranch Hand
Posts: 108
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
author and jackaroo
Marshal Commander
Pie
Posts: 12007
215
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
    Ranch Hand
    Posts: 108
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    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
    author and jackaroo
    Marshal Commander
    Pie
    Posts: 12007
    215
    C++ Firefox Browser IntelliJ IDE Java Mac Oracle
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    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
    Ranch Hand
    Posts: 44
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    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
    Ranch Hand
    Posts: 108
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    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
    Ranch Hand
    Posts: 108
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    I was wondering when i stop writing desisios with 's'.
     
    Jim Yingst
    Wanderer
    Sheriff
    Posts: 18671
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    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
    Ranch Hand
    Posts: 61
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    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
    author and jackaroo
    Marshal Commander
    Pie
    Posts: 12007
    215
    C++ Firefox Browser IntelliJ IDE Java Mac Oracle
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    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
    Ranch Hand
    Posts: 527
    1
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    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.
     
    • Post Reply
    • Bookmark Topic Watch Topic
    • New Topic