• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

User documentation

 
Yan Zheng
Greenhorn
Posts: 5
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 3451
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
Yan Zheng
Greenhorn
Posts: 5
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thanks Michael, that's helpful.
 
Samual Harvey
Ranch Hand
Posts: 119
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
Michael Morris
Ranch Hand
Posts: 3451
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Samual,
All of it.
Michael Morris
 
Samual Harvey
Ranch Hand
Posts: 119
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
How is Online help documentation different from user documentation and also from javadoc.
Thanks.
 
Michael Morris
Ranch Hand
Posts: 3451
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic