Win a copy of Re-engineering Legacy Software this week in the Refactoring forum
or Docker in Action in the Cloud/Virtualization forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

User Documentation

 
Rasika Chitnis
Ranch Hand
Posts: 131
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 102
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
Rasika Chitnis
Ranch Hand
Posts: 131
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 17278
6
IntelliJ IDE Mac Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
Rasika Chitnis
Ranch Hand
Posts: 131
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 17278
6
IntelliJ IDE Mac Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 131
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 17278
6
IntelliJ IDE Mac Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 131
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 17278
6
IntelliJ IDE Mac Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 11
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 17278
6
IntelliJ IDE Mac Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
"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
Posts: 11
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 17278
6
IntelliJ IDE Mac Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Yes, your results will be posted at My Certification at Galton's site
Good Luck
Mark
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic