readme.txt

[Raffe Paffe]

I am working on my readme file and i wonder how much setup information that i need to provid.
Can i assume that "they" have a working java installed?
That rmiregistry is in the path?

If any environmental setup is required, do not just say what needs to be done; provide instructions on how to perform the setup.

This doesn say that much.
Here is my readme so far:

1. JDK Version and Platform
The exact version of JDK used for this project is:
java version "1.3.1_07"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1_07-b02)
Java HotSpot(TM) Client VM (build 1.3.1_07-b02, mixed mode)
The following information details the exact operation system information:
Microsoft Windows 2000
5.00.2195
Service Pack 3
2. Execution Instructions
The Fly By Night application can run in local or remote mode.
2.1 Local Mode
In local mode, you only need to run the client application.
To do this, run the following command from a command window:
java -jar client.jar <<put db location here>>
Like this:
java -jar client.jar db.db
(make sure that db.db is in the same directory)
db.db is the name of the database file. If you have another name put it where db.db is.
2.2 Remote Mode
In remote mode, you need to start the server in one jvm and the client in another jvm.
You must also start the rmiregistry, so the server can bind to the registry.
To do this enter the folder where server.jar is located.
Issue the following command(on windows 2000) to add server.jar to the classpath:
set CLASSPATH=%CLASSPATH%;server.jar
Then start the rmiregistry like this:
rmiregistry
To start the server (make sure that db.db is in the same directory)
run the following command:
java -jar server.jar
To start the client:
java -jar client.jar <<put db location here>> <<put server location here>>
Like this:
java -jar client.jar db.db 127.0.0.1
3. Location of Data File
The data file called db.db is located root of the jar.
4. Location of Documents
The design choices document called designchoices.txt is located root of the jar.
The help document help.txt is located root of the jar.
The readme document called readme.txt is located root of the jar.
5. File Listing
The following list outlines the names of the files in the directory,
with a note of their location in the directory structure, and a high level description of the purpose of each.
client.jar The client application (executable jar file)
server.jar The server application (executable jar file)
Devassnmt2.jar The original jar file for this assignment
src.jar The jar file containing the java source files
doc.jar The java documentation
db.db The original data file for this assignment
designchoices.txt The document describing the design choices made
help.txt The user manual file
readme.txt This file
Thanks

[Andrew Monkhouse]

Hi Raffe,

I am working on my readme file and i wonder how much setup information that i need to provid.
Can i assume that "they" have a working java installed?
That rmiregistry is in the path?

I think this is a reasonable assumption.
I think that writing instructions detailing how to download and install the Java runtime would be overkill. However, you could probably have a comment near the start of your execution instructions stating that it is assumed that the user has installed a working version of the runtime, and that the Java executables (java, rmiregistry) are in the path.

In local mode, you only need to run the client application.
To do this, run the following command from a command window:
java -jar client.jar <<put db location here>>
Like this:
java -jar client.jar db.db
(make sure that db.db is in the same directory)

Be vewy vewy sure that this can in fact be done (sorry, just watching some Bugs Bunny & Elmer Fudd cartoons). Reading this instruction, I might be tempted to open a command window and type these commands without changing to the directory where I unpacked your jar file. At the point these commands are given, you have made no mention of CLASSPATH, so this command would fail if I was in the wrong directory.
In your "remote mode" instructions, I recommend that you change the order of your general instructions, so that it specifies starting rmiregistry first. It saves a little bit of confusion where the general instuctions are in a different order than the specific instructions.
I understand what you are meaning when you say "root of the jar", but will your users? While acknowledging that the user will have to be technically savy, I think we need to write as though it is a dumb end user (or a sys admin) that will be setting everything up - someone who may not understand that phrase. I am still trying to work out the best phrase, but I would prefer "the base directory into which the deliverable jar was unpacked." Too verbose?
--
Does this mean that you are about to submit?
If so, and just out of curiosity, how many OS'es did you test on, and were they clean systems? (that is no JDK installed, just runtime). Did you give it to some "dumb" end user's to test? (My girlfriend used to work in technical support and system test departments in the past, but knows no Java - I am afraid of how much she will find when she starts testing )
Regards, Andrew

[Raffe Paffe]

Very good points Andrew.
No I am not ready to submit yet. But I can see the end of this assignment. I will be writing documentation and starting tests this week.
Thanks for posting your comments!
Is this better:
2. Execution Instructions
The Fly By Night application can run in local or remote mode. It is assumed that
the user has installed a working version of the java runtime, and that the Java executables (java, rmiregistry)
are in the path. All commands that that are shown in these instructions are to be executed the same folder
were the original jar file was unpacked. So if you are about to run java -jar client.jar db.db for example
make sure that both client.jar and db.db are in the same folder where you are about to issue the command.
[ April 14, 2003: Message edited by: Raffe Paffe ]

[Andrew Monkhouse]

Hi Raffe,
Looks good to me.
Regards, Andrew

[Saraswathy Krishnamoorth]

Hi Raffe,

To start the client:
java -jar client.jar <<put db location here>> <<put server location here>>

One small clarification. During Remote mode why do you need to specify the location of db.db when you execute the client.jar. The server should know the location of db.db.

[Raffe Paffe]

Saraswathy :
No, I should changed that to just the name of the db , not the location.
Thanks

[Sarita Gupta]

Hi all,
Just to check, do I have to document how to install and execute the application in both Unix and Windows environment.
Also, it's said that
All submissions must be packaged in a JAR file.
Does it mean that we can only submit a single jar file. In which case, my README.txt will be in the jar file(which will be in the install directory after extracting). Should that be the way... pls comment
Advice is appreciated. Thank you.
Sarita

[Andrew Monkhouse]

Hi Sarita,

do I have to document how to install and execute the application in both Unix and Windows environment.

It would not be possible to document how to install and execute the application in every environment that Java runs on, even if you tried to limit it to those with GUIs. So all you have to do is document how to install and execute it on the platform you developed on.

Also, it's said that
All submissions must be packaged in a JAR file.

This should have been in your instructions when you downloaded the assignment. Please check, because you must follow your instructions to the letter or you could fail.
The normal way to package the assignment is to have one jar file wich contains everything else: the README, client software (possibly in a jar file), the server software, the API documentation, the user documentation ....
Regards, Andrew