Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

User Documentation - ascii text file format ?

 
Eugene Sun
Greenhorn
Posts: 17
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi guys,
I am working on the final documentations for the assignment. I am thinking to just use ascii text file format for the user documentation with plain text to instruct user how to use the GUI and the server.
Has anyone done that and passed the exam without being penalized ?
another question,
in the "Deliverables" part of the instruction of my assignment, btw, I am on FBN assignment. It requires me to document how to execute the programs in README.txt. Isn't that redundant with what's required in the user documentation where I am supposed to document how to run the programs ?? How are you handling this ?
Thanks,
Eugene
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Eugene,
Plain ascii text file format was permitted for the user's guide in my assignment instructions (for the B&S assignment). If your instructions permit the same format I don't see why you would be penalized for using it.
My instructions said one could provide the user's guide in any of these formats: on-line, in HTML format, or plain text. I think we should take this sort of requirement at face-value; that is, you don't get more or less points if you implement the on-line version, rather than the plain text version.
There is probably some overlap between the user's guide and the readme.txt file. The focus of the readme.txt file should be how to get the application up and running. For example, the readme.txt file could contain some of the following things:
1. Introduction
2. Installation
3. Execution Instructions
4. SDK Version and Platform
5. Location of Data File
6. Location of Design Choices Document
7. Location of User Documentation
8. File Listing
The focus of the user's guide should probably be more about how the user accomplishes certain things while running the application.
Hope this helps,
George
 
Mark Spritzler
ranger
Sheriff
Posts: 17278
6
IntelliJ IDE Mac Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Eugene. Although not necessary, I would highly suggest creating your user documentation as an HTML page that you display in a Simple screen with a JScrollPane. It will give you a little experience with it, and it is very simple to implement and shouldn't take to much time.
The Design and instructions to the assessor can be in text format, as mine was.
Mark
 
Jay Bromley
Ranch Hand
Posts: 48
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Eugene,
I agree with Mark. Since I'm new to Java, for me this project is a great learning experience in addition to a cert. An ASCII help file is the easiest way out, but you have to ask yourself, "Would I be happy with an app that only provided offline plaintext help?" My answer was "probably not."
This lead me to using DocBook to create documentation and developing a simple HTML viewer to look at it. On the way, I learned about some good ways to handle documentation for Java apps (JavaHelp + DocBook), which for me is the most valuable part of all this. No, I supposedly won't get more points than someone who does a simple ASCII text file, I would think it makes a better impression on the grader. On the other hand, Mr. Krebs provided a text user guide and scored very well.
In summary, if you've already got a good way of doing help or its not important for you, go with plain text. If you're taking this as a learning project, do some investigation on creating help.
Regards,
jb
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi All,
I'm not against doing extra things for the project as long as you understand why you are doing them. For example, I implemented an on-line user's guide that extensively utilized hyperlinks and had a Back button that could return the user to previously viewed locations in the document. However, none of this was required, I don't think it will make a better impression on the grader, and therefore I doubt that it will get me a higher score than if I had simply provided the required user's guide document in plain text.
I really do think simplicity in meeting the requirements is one of the prime directives in delivering a successful project. I didn't follow this advice myself and it therefore took me much longer to finish the project than it should have. Also, realize that when one adds anything beyond the minimal requirements that the potential for bugs increases. So it seems to me that there's very little upside to adding non-required features, and a larger potential downside to doing so.
If you do add extra features, do so because you want to, because you want to increase your knowledge and experience, not because you think you'll get a higher score on the exam. Also, be careful that bugs in your extra features, don't interfere with the proper functioning of your implementation of the required features.
Hope this helps,
George
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic