Design document

[Chandru Ganesan]

Hi All,
I am new to Java Ranch. I found some useful insights to Java certification in this site and am
happy to be a member of this site.
I am working on the documentation for Developer certification. I have following questions.
1. I dont have access to Rational's UML tool to document the class and sequence diagrams. Are design class and sequence diagrams absolutely necessary to score 100% in the documentaion?. If yes,is there any Windows based UML tool that I can download from the web?
2. As per the assignment that I received I am supposed to document the following in the design document
a. Major design choices and reasons
b. RMI vs Serialization
c. Modifying vs Extending
Is it possible for anybody to score 100% in documentation by just documenting the above info in a MS-Word document without any diagrams. My understanding based on the assignment requirements is, extra points wont be awarded for doing what is more than enough. Please correct my if I am wrong.
3. Has anybody used the Jindent tool for generating
java source code formatting and javadoc generation. If so, does it releive me from the responsibilty of understanding all HTML tags for javadoc generation?.
I read the book by Mehran Habaibi et al and it really helped me finish my application in less time than I originally envisaged. I learnt a lot from this book and I'd certainly recommend it.

thanks
Chandru Ganesan

[griffith jones]

Chandru:
I just received my SCJD score on Friday: 147/155,
and here is my experience, for what it's worth:
I included no UML diagrams, just the javadoc HTML, as required. I did not lose any points for documentation (20/20).
I documented 13 major design decisions, including RMI vs. sockets, and Data class extension
vs. modification. For each choice, I discussed at least 2 alternatives, and then presented the pros and cons of my choice. In total, my design choices doc was 4 pages in length, simple text format.
My followup exam did not quiz me on javadoc. If you have run javadoc against your code and are happy with the output, you are probably done.
I declared Windows 2000 as my OS, but also tested it with Solaris7. The code ran on Solaris, with no re-compilation needed. I used only one jar file for all my code. I had no security policy whatsoever, and no GUI for my server. I invoked the registry from within my server code, to keep things simple. My user guide was a simple text file that took 30 minutes to assemble.
It's my impression that many people do much more than needed for this assignment. In my opinion, the name of the game here is NOT losing points, as opposed to submitting a coding tour-de-force with every concievable bell and whistle.
Good luck ...
Griffith

[Chandru Ganesan]

Griffith
Congratulations and thanks for useful info.
Chandru

[John Smith]

1. I dont have access to Rational's UML tool to document the class and sequence diagrams. Are design class and sequence diagrams absolutely necessary to score 100% in the documentaion?. If yes,is there any Windows based UML tool that I can download from the web?

No diagrams are required, but if you want to layout your design for yourself, you can use UML Pad, -- it's very simple to use and it's free.

in a MS-Word document

You cannot use any Microsoft-specific format for your documentation or any other files. The requirements are very specific about it, -- either use HTML or plain text. The accessor may not even have MS Word installed, -- it may not even be a Windows machine.
Eugene.

[Chandru Ganesan]

Eugene,
Thanks for the info. I have one additional question.
Since I dont have access to unix box or windows 2000 I have tested my application under windows me. Is that ok as long as I document it in the README.txt
Chandru

[Chandru Ganesan]

Can I save my MS-Word document as a web page [html] document. will this work?. If not how do I convert my word into an HTML document

[griffith jones]

Chandru:
I'm assuming you currently have access to MS Word or MS Works.
You should be able to morph your MS Word document into HTML format by selecting FILE/SAVE AS, and then selecting HTML as the "save as type".
In terms of OS, any flavor of Windows should be fine. I suspect that the majority of submissions were created under Windows, with Solaris and other Unix variants a distant second. Your compiled classes should be byte-code compatible across the entire Windows landscape.

If you are using an IDE that features it's own Java compiler, i.e. VisualAge, just be sure to recompile your code using the Sun JDK ...
Griffith

[Chandru Ganesan]

"You should be able to morph your MS Word document into HTML format by selecting FILE/SAVE AS, and then selecting HTML as the "save as type".
that's exactly what I did. thanks
I plan on submitting both user doc and api doc in HTML format, online. My question is how do I do that?
thanks
Chandru

[griffith jones]

Chandru:
There are about a thousand ways to skin this cat.
My javadoc HTML went within a /javadoc directory in my submission Jar.
I created a /doc directory which contained the User Guide in text format. My GUI contained a "Help" menu item that displayed the User Guide in a non-editable JScrollPane.

Others have used HTML for this function and popped up the HTML from within their GUI. I'd suggest doing a search for "HTML" within the Developer Certification forum, I remember this issue coming up recently.
Griffith

[Peter den Haan]

Griffithjo, please read the naming policy and change your display name. Thanks.
The "save as HTML" option of Word does not save HTML. It saves a document that looks faintly like HTML and displays correctly in Internet Explorer, but it is definitely not HTML. It contains horrors such as overlapping tags, and you cannot rely on anyone but IE-users to view it.
Fortunately there is a simple cure. Run HTMLTidy over your document with the word option and you should be fine. It will also strip out all the extra fluff that Word inserts to facilitate round-trip editing and the file will end up being a lot smaller as well. This little free tool is warmly recommended for all your HTML validation, formatting and repair duties!
- Peter
[ February 09, 2003: Message edited by: Peter den Haan ]

[Chandru Ganesan]

Peter,
I encountered the same problem that you identified. Will try HTML Tidy and see if it works.

thanks
Chandru

[Chandru Ganesan]

I created a simple word doc with just 1 line of text. Saved it as a web page document and input this doc to tidy for clean up. Tidy is unable to convert it.
The erros is
'this document has errors that must be fixed before using HTML tidy to generate tidied up version'
I think I may have more problems if I try to convert a picture from ms-word [screen snapshot imported into a ms-word doc] into HTML.
Is there any HTML editor that woud allow me to create HTML file, import pictures & edit text

thanks
Chandru

[Miguel Roque]

Hello.
I'me creating the user documentation using Max's HTML Beauty++ ME
It's nice and free, can run HTMLtidy in the page you are writing.
Best regards,
Miguel

[Peter den Haan]

To be honest, it's been so long ago, I can't remember if I had to patch up the file before I could successfully run htmltidy.
The htmltidy homepage mentions a new version of the Microsoft HTML output filter that would be much better. Maybe that's a possible avenue to explore?
- Peter

[Chandru Ganesan]

Is there any drawback in submitting the HTML document only as part of the jar file instead of providing it as part of online help.
Also I plan on including 5-6 screen snapshots in the user interface doc. I worry that it could increase the size of my jar to > 432 k which I beleive is an ideal jar file size.
any comments?
thanks
Chandru

[Peter den Haan]

Originally posted by Chandru Ganesan:
[...] I worry that it could increase the size of my jar to > 432 k which I beleive is an ideal jar file size.

Ummmm... you didn't take that seriously, did you? By all means do include a few screenshots if you wish.
- Peter

[John Smith]

Also I plan on including 5-6 screen snapshots in the user interface doc. I worry that it could increase the size of my jar to > 432 k which I beleive is an ideal jar file size.

Chandru,
I was joking, of course, about the 432K as the "best" jar size, -- I thought it was a transparent joke. Clearly, there is no such thing as "the best size", -- this assignment is all about the clarity, simplicity, and reusability of your design. So, if you think that your snapshots will add value to user doc, do include them, by all means. However, if you decide to include the pictures of the airport buildings/plans, make sure that they reflect the design principles outlined by Christopher Alexander.
Eugene.
[ February 10, 2003: Message edited by: Eugene Kononov ]