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

userguide.txt

 
Gytis Jakutonis
Ranch Hand
Posts: 76
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hello,

my userguide is only 150 lines long (up to 80 characters in line, ~7.5kb) - is it too small? some people mentioned userguides of 12 pages or smth like that - I'm a bit cunfused - is it necesary to write 12 pages in order to explain one screen with 2 business functions (search and book) and ~6 gui controls?
I have small sections on installation and setup, but I'm not sure about details like how to setup PATH and CLASSPATH - is it necessary?

thanks in advance
 
Andrew Monkhouse
author and jackaroo
Marshal Commander
Pie
Posts: 11854
185
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Gytis,

Probably the best way of determining whether your userguide is suitable or not is to try giving it (and your application) to an "end user" - someone who is not familiar with your application / it's requirements / how to configure it. Then see how they go with running it and using it.

But, you have to be honest about it - if they have a problem, don't lean over the desk and point out the one thing that will clear up their problem - go back and fix your documentation.

Regards, Andrew
 
Gytis Jakutonis
Ranch Hand
Posts: 76
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I already tried this option - I left my submission and intro (from instructions) to my wife - she had no problems with starting up and testing all modes. BUT I'm a bit concerned since she has master's degree in IT and works as net admin So the question is: which level does userguide need to address - total novice (which does not know what combobox means) or a bit experienced (which understands sentence 'run command java ... in submission directory')?
 
Andrew Monkhouse
author and jackaroo
Marshal Commander
Pie
Posts: 11854
185
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Gytis,

I think it is logical to assume some knowledge of how to start applications, and possibly some knowledge of the business domain.

As I understand it, the intent of getting people to write user documentation is to show that developers do know that they have to write user documentation, and can do so. And if your wife could follow the instructions without problems, then it sounds like you are meeting these critieria.

You said you have about 150 lines of text - this would equate to about 3 pages if you did it up in a word processor. Sounds reasonable for the size of this project.

Regards, Andrew
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic