aspose file tools*
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes User Documentation Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "User Documentation" Watch "User Documentation" New topic
Author

User Documentation

Rasika Chitnis
Ranch Hand

Joined: Jun 19, 2001
Posts: 131
I am confused about where exactly I should include User Documentation. Should it be in the README.TXT file or a separate file in the docs directory ? Under Deliverables section in the instructions.html that came with the downloaded assignment, it is sort of indicated that the User Documentation should be a part of the README.TXT file. But, there are five bullets desribing what is to be covered in this file and I don't find User Documentation in any of these bullets. The instructions also say that the contents of the README.TXT file have to be exactly in the same order as it is given under these five bullets. I read somewhere that one has to be very careful about the sequence in which README.TXT file is written since the contents of this file are probably extracted programmatically. Also, what exactly goes in the User Documentation ? How to execute the program from the command line or how to use menu items, buttons, hot keys and other GUI components etc ?
I would like to get reply from the people who have already passed about this.
Terry Wang
Ranch Hand

Joined: Aug 27, 2001
Posts: 102
it's better to have a seperate html user manuel to teach the user how to set up and run the app.
in my manuel, i have:
1) introduction to fbn app;
2) setup
3) how to run (both modes)
4) faq (trouble shootings)
each section is brief, and with some screen shots.


scjp/jd/wcd/mcad/scea 1
Rasika Chitnis
Ranch Hand

Joined: Jun 19, 2001
Posts: 131
I actually have the online HTML help file that explains how to start the application in both modes and how to do a search and book the flight. But I am not sure if I should repeat the same in README.TXT file as well.
Mark Spritzler
ranger
Sheriff

Joined: Feb 05, 2001
Posts: 17259
    
    6

the contents of the Readme file are specifically written in the Specs. It tells you to include how to run your app, and the files that you are submitting.
Please read the instructions.html that came with your assignment and it should clear things up.
If not, just post here.
Mark


Perfect World Programming, LLC - Two Laptop Bag - Tube Organizer
How to Ask Questions the Smart Way FAQ
Rasika Chitnis
Ranch Hand

Joined: Jun 19, 2001
Posts: 131
Mark,
The instructions that came with the assignment at one place say which things to include in the README.TXT file. There are five things listed and we are supposed to follow exactly the same order in which the things are listed. One of the things is how to run the application i.e. command line syntax, setting env variables etc. But User Documentation (e.g. how to actually use the menu, buttons etc) is not part of the list.
However, in another paragraph under 'Deliverables' section, it is mentioned that "your user documentation may be online if you wish but there must be one file in the root directory of your submission called README.TXT". To me, instructions are confusing. I guess I want to clarify that there is separate User Documentation other than instructions on how to use the application.
Mark Spritzler
ranger
Sheriff

Joined: Feb 05, 2001
Posts: 17259
    
    6

User documentation and the readme.txt file are two different things.
readme.txt are those five things like you mentioned.
User Documentation is how to use the program, like How do I book a flight, what do all those buttons mean, what is that Grid looking thing, How do I search. Those kind of things.
Mark
Rasika Chitnis
Ranch Hand

Joined: Jun 19, 2001
Posts: 131
thanks, Mark. I agree with you that User Documentation and README.TXT are two different things. So, are you saying that User Documentation should not be part of README.TXT file. But instructions.html say following :
"your user documentation may be online if you wish but there must be one file in the root directory of your submission called README.TXT"
Where do you think the User Documentation should go ? in a separate file other than README.TXT ? and probably mention about this file in README.TXT ?
Mark Spritzler
ranger
Sheriff

Joined: Feb 05, 2001
Posts: 17259
    
    6

Yes, in two seperate files.
To give you an idea. my readme.txt had how to run the app, meaning what java command to use. and a list of all the files that are in the submission jar file.
In the User Documentation, which for me was HTML pages, that was opened in a Documentation class, that is a JFrame with a JScrollPane. This JFrame was opened from a menu item in my server and client GUI. So I had Two User Doc HTML pages. One for the Server, and one for the client.
Hope that helps clear it up a little more.
Mark
Rasika Chitnis
Ranch Hand

Joined: Jun 19, 2001
Posts: 131
Thanks for clarifying things. I was just worried about getting penalized because I have not written User Documentation in README.TXT.
In my case, too, I have User Documentation on line i.e. in HTML file and I launch that when user clicks on "Help Topics" menu item. I am just curious that you had GUI for server and you open the server user documentation HTML file from server GUI. What GUI you provided for server ??
Mark Spritzler
ranger
Sheriff

Joined: Feb 05, 2001
Posts: 17259
    
    6

A very basic GUI. One button for shutting down the server, a menu for File/Exit, which did the same as pressing the button, and Help. Then under the button was a JLabel that would say what was going on with the server. Most of the time it said "Waiting for Connection".
Mark
Vivek Rana
Greenhorn

Joined: Feb 19, 2002
Posts: 11
Do we need to include the screen shots as well in our user documents ?
how long would you think it should go ?
as application functionality is very small mine is of just couple of pages.
But as it carry 10 marks, i am just thinking what else i should include here ?

Rana
Mark Spritzler
ranger
Sheriff

Joined: Feb 05, 2001
Posts: 17259
    
    6

"Rana"-
Welcome to the JavaRanch! Please adjust your displayed name to meet the
JavaRanch Naming Policy.
You can change it
here.
Thanks! and welcome to the JavaRanch!
And you can include screen shots if you would like. I included them in mine and I got 10/10 in the doc portion.
Mark
Vivek Rana
Greenhorn

Joined: Feb 19, 2002
Posts: 11
Thanks Mark !!
I have uploaded and given the exam yesterday,
lets see how much i will get.
Where will they post the result ?
in mycertification or some where else ?

Rana
Mark Spritzler
ranger
Sheriff

Joined: Feb 05, 2001
Posts: 17259
    
    6

Yes, your results will be posted at My Certification at Galton's site
Good Luck
Mark
 
 
subject: User Documentation