• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

User documentation

 
Greenhorn
Posts: 5
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.
 
Ranch Hand
Posts: 3451
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Thanks Michael, that's helpful.
 
Ranch Hand
Posts: 119
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hi Samual,
All of it.
Michael Morris
 
Samual Harvey
Ranch Hand
Posts: 119
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
 
reply
    Bookmark Topic Watch Topic
  • New Topic