Win a copy of Svelte and Sapper in Action this week in the JavaScript forum!
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Ron McLeod
  • Paul Clapham
  • Bear Bibeault
  • Junilu Lacar
Sheriffs:
  • Jeanne Boyarsky
  • Tim Cooke
  • Henry Wong
Saloon Keepers:
  • Tim Moores
  • Stephan van Hulst
  • Tim Holloway
  • salvin francis
  • Frits Walraven
Bartenders:
  • Scott Selikoff
  • Piet Souris
  • Carey Brown

how verbose should be design desision document?

 
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?
 
author and jackaroo
Posts: 12199
280
Mac IntelliJ IDE Firefox Browser Oracle C++ Java
  • 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
    Posts: 12199
    280
    Mac IntelliJ IDE Firefox Browser Oracle C++ Java
    • 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
     
    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'.
     
    Wanderer
    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.
     
    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
    Posts: 12199
    280
    Mac IntelliJ IDE Firefox Browser Oracle C++ Java
    • 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
     
    Ranch Hand
    Posts: 531
    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.
     
    Space seems cool in the movies, but once you get out there, it is super boring. Now for a fascinating tiny ad:
    Building a Better World in your Backyard by Paul Wheaton and Shawn Klassen-Koop
    https://coderanch.com/wiki/718759/books/Building-World-Backyard-Paul-Wheaton
      Bookmark Topic Watch Topic
    • New Topic