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.
posted 16 years ago
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?
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.
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
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.
Shivaji - those are good questions. Here's how I got around those problems first for the path
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
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
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
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
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
posted 16 years ago
hi, guys: I made a stupid mistake. Thank for all your replies. Xiaoma Wang