File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
http://aspose.com/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

Yan Zheng
Greenhorn

Joined: Jul 21, 2002
Posts: 5
I am writing user documentation, but not sure how far should I go. Any scjd please comment on this, e.g. length, detail level, etc.
Like most programmer, I hate to write user doc and want to keep it as simple as possible.
Michael Morris
Ranch Hand

Joined: Jan 30, 2002
Posts: 3451
Hi Yan,

Like most programmer, I hate to write user doc and want to keep it as simple as possible.

Yeah, it's like cleaning the toilet, ain't it? But you know you gotta do it or the bathroom starts stinking. I provided pretty thorough user documentation, providing screen shots and step by step usage of menus, accelerator keys, etc. Look at it this way: Have you ever tried to learn an application with less than adequate documentation? Do you want your users to think you're a bozo? So my advice is, come up with enough documentation that an average user can use to learn the interface you have developed.
Hope this helps,
Michael Morris


Any intelligent fool can make things bigger, more complex, and more violent. It takes a touch of genius - and a lot of courage - to move in the opposite direction. - Ernst F. Schumacher
Yan Zheng
Greenhorn

Joined: Jul 21, 2002
Posts: 5
Thanks Michael, that's helpful.
Samual Harvey
Ranch Hand

Joined: Aug 06, 2002
Posts: 119
What all documentation from the list below is required:-
1. User documentation.
2. Design Documentation.
3. ReadMe.txt
4. Online Help documentation
5. HTML javadoc.
Thanks.


Samual Harvey<br />SCJP2<br />SCJD2
Michael Morris
Ranch Hand

Joined: Jan 30, 2002
Posts: 3451
Hi Samual,
All of it.
Michael Morris
Samual Harvey
Ranch Hand

Joined: Aug 06, 2002
Posts: 119
How is Online help documentation different from user documentation and also from javadoc.
Thanks.
Michael Morris
Ranch Hand

Joined: Jan 30, 2002
Posts: 3451
Hi Samual,

How is Online help documentation different from user documentation and also from javadoc.

Online help and user documentation are essentially the same thing. Online implies HTML format. In my case, the user could access the documention thru the Help menu on client or server, and could also open it up in a web browser without starting either client or server.
Javadoc is your application's API. You should put javadoc style comments just before each class, method and field, at least each that is either public or protected. Javadoc comments are similar to regular block comments except they start with 2 stars instead of one like this:

You generate the javadoc API with the javadoc command.
Hope this clears it up,
Michael Morris
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: User documentation
 
Similar Threads
Readme must list every file?
How to provide user documentation?
JUnit tests guidelines
Design Documents Format
User Documentation