Design Documents Format

[Mathew Sam]

Can i create user documentation and design choices in MSWord.

[Enrico Mannarino]

No, you can't.
See Instructions: "A README.txt file. You must create a single text file (plain ASCII format; word processor formats are unacceptable)"

[Mathew Sam]

That is about Readme file .What about design choices document and User manual ?

[Enrico Mannarino]

I just assume it's the same. But you're right. It's not really clear!

[Donald Wedding]

I am also currently working on my design document and had the exact same question.
I am just going to play it safe and create an ASCII text file.
I figure if we *BOTH* do it, they can't flunk us both right? Just wouldn't be very sporting of the guys at SUN.

[Enrico Mannarino]

I have a problem with this: "Also provide user documentation for the database server and the gui client"
Is the user the end-user; i.e. the person who wants to use the application to book a flight or is the person who is gonna start the applications?
If the user is actually the end-user, it doesnn't make sense to put information about the server and db in there, just GUI staff?!
Any ideas?

[Mark Spritzler]

Also provide user documentation for the database server and the gui client

This is like a manual. It explains how to run the program.
What I did was to make a simple HTML page with the user documentation. One for the client/GUI and one for the server. I put the HTML page on a JFrame with a JEditorPane and a JScrollPane and a menu with an exit option.

 
URL helpURL             = new URL(documentationURL);
            editorPane.setPage(helpURL); 

The URL() constructor takes a string that is the path and filename of the .html file.
Both the server and my client had GUIs and had a help menu item, that would call up this Documentation class and put the correct HTML file in the JFrame, and display the Frame.
But most people don't have a gui for the Server. I wanted one so I could have the Help file there.
My server gui was simple, just a Menu, a button saying "Stop Server", and a "Status line" saying what the server was doing, which most of the time said "Waiting for client request"
Mark

[Enrico Mannarino]

Thanks a lot, Mark

[Andre Tow]

I've written mine in ASCII as well, I figured
ASCII and/or HTML is probably the only thing that
would be cross platform..

[Gregory Garrison]

Somebody has already failed first time round by not supplying the txt file. Make sure you include this file. This person's post is on this site somewhere.

[Shivaji Bhosale]

I have a doubt over Mark's documentation with the usage of JEditorPane. Its good thing to implement.
But as per code, documentationURL has to be some file path.
Now my appn path is say,
c:\exam, & below exam I am having suncertify.db, suncertify.client. Below exam I am creating one more dir called say 'help' for my user documentation.
I set my documentationURL as 'file:///c:/exam/help/doc.htm' in the program,
Then how come I can ensure for examiner to install my application to c:\exam ?
Say If I decide to provide properties file, for Help file settings, its specifically mentioned, that, examiner shouldnt asked to edit any file.
Then, my question is how I can keep my online documentation flexible, without hardcoding URL ?
If I decide to give a relative path say as .//help//doc.htm, this relative path is appended against which path ?
After setting classpath if i am executing my application from some other path, then there will also other problem of not getting help page.
2nd question is, keeping user guide online (HTML), gives good flexibility of showing help. Is it ok, assuming examiner having HTML browser. This one might be stupidest question, but still dont want to take up risk.

[Mark Spritzler]

Shivaji - those are good questions. Here's how I got around those problems
first for the path

 String documentationURL     = "file:"+ System.getProperty("user.dir") + System.getProperty("file.separator") + htmlDocument; 

user.dir gives you the start of the classpath, whatever one is set when the app starts.
No Properties files needed.
I kept the .html file in the root directory as my executable jars.
#2 question - They do not need a browser, It doesn't open up a browser. The JEditorPane is the "Browser", it takes a URL class and shows it. Pretty cool huh?
Mark

[Shivaji Bhosale]

Mark,
My 2nd Qn was, If i decide not to implement with JEditorPane, is it ok, to assume with, examiner is having some HTML browser for viewing online user document, external to application ?

[Mark Spritzler]

Oh, no I don't think it is safe to say they have a browser for sure. That's why I used a JEditorPane. It was just really easy. Also the readme and design documents of mine are in text files .txt, and are not shown in the JEditorPane. Just so no one gets confused as to what I had in HTML.
Thanks
Mark

[xiaoma wang]

hi, Mark:
I read your post about the document and learn a lot. One thing i want to ask about your design: u said that in the client, there is a help menu item and when it is clicked, create a Document, and put it on the editorPane, and this editorPane is placed on a JFrame, at last the frame is displayed. u have two frames in the client GUI? if yes, how to handle them? i mean, how to control the switch b/w the two frames? u use JInternalFrame class?
Thank u very much!
Xiaoma Wang

[Mark Spritzler]

u have two frames in the client GUI?

Do you mean my main JFrame which has the "Booking" screen, and the second being the Help window. If you mena that then yes, I have two JFrames.
One is called from the other. If you are in the main booking screen and select Help from it's menu, then the Help JFrame is displayed. No other tricks needed. Oh, and the first JFrame is always visible.
Mark

[Adam Caldwell]

You can provide your documentation as HTML (except for the README.txt) and get all of the documentation points. My user documentation, client documentation, and design docs were all in HTML format and I got 20/20 on the doc portion.
-Adam

[xiaoma wang]

hi, guys:
I made a stupid mistake. Thank for all your replies.
Xiaoma Wang