This week's giveaway is in the Android forum.
We're giving away four copies of Android Security Essentials Live Lessons and have Godfrey Nolan on-line!
See this thread for details.
The moose likes Meaningless Drivel and the fly likes How to write efficient User Guide... Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Android Security Essentials Live Lessons this week in the Android forum!
JavaRanch » Java Forums » Other » Meaningless Drivel
Bookmark "How to write efficient User Guide..." Watch "How to write efficient User Guide..." New topic
Author

How to write efficient User Guide...

ankur rathi
Ranch Hand

Joined: Oct 11, 2004
Posts: 3830
Hi,
This is not meaning less but I couldn't find forum for this. I am told to write User Guide. Please help me in this, what should go in user guide and what should not...

Thanks a lot.
Jeroen Wenting
Ranch Hand

Joined: Oct 12, 2000
Posts: 5093
Don't put too much meaningless drivel in it


42
R K Singh
Ranch Hand

Joined: Oct 15, 2001
Posts: 5371
I am not sure but you can refere some other User guide's available with MS apps.

Let me assume that you want to write USerGuide for some application.

I think first you should divide your application in different parts. Start with "Introduction", that would contain the brief of over all application and modules of appliction.

Granulate the modules as much as possible. First only write the headings for each modules and sub modules.

If your headings cover your whole application then you can expalin each sub/module under each heading.

It could be much better than that but for that some generous author has to spend some time on this thread.


"Thanks to Indian media who has over the period of time swiped out intellectual taste from mass Indian population." - Chetan Parekh
Ernest Friedman-Hill
author and iconoclast
Marshal

Joined: Jul 08, 2003
Posts: 24183
    
  34

Writing user manuals is hard in my experience.

My suggestion -- something that I feel has helped me a lot -- is to use a machine-checkable format, then write scripts to check everything you can. For example, write a script that checks that every menu item is documented, and every dialog box, etc. Make sure the tests run both ways -- i.e., confirm that every documented item is actually in the software. Then run these scripts as part of your application test suites. This way, when the software changes, you'll get an automatic report of where the documentation needs to be fixed.

I've used various XML-based formats for this in recent years (DocBook, homebrew), and I've used TeX in the past. Anything easy to parse is good. I guess even Word is OK if you can write scripts in Visual Basic or something that can examine Word files -- I'm not sure if this is possible or not.


[Jess in Action][AskingGoodQuestions]
Aj Mathia
Ranch Hand

Joined: Apr 11, 2003
Posts: 478
a search in google popped this which looks quite ok
http://www.klariti.com/technical-writing/User-Guides-Tutorial.shtml


You think you know me .... You will never know me ... You know only what I let you know ... You are just a puppet ... --CMG
Stan James
(instanceof Sidekick)
Ranch Hand

Joined: Jan 29, 2003
Posts: 8791
Three things I learned from old IBM manuals. 1) They published two manuals for every product: a "reference manual" that showed every possible option and explained their effects in great detail, and a "user guide" that showed some typical goals and how to reach them. You can make a real mess trying to combine the two manuals. 2) A really excellent index is essential when you want to find something in a hurry. 3) Disambiguate! They never used a short article (?) when a descriptive noun would do, even if it means repeating the same noun over and over in one sentence. You almost never see "it" in a sentence.


A good question is never answered. It is not a bolt to be tightened into place but a seed to be planted and to bear more seed toward the hope of greening the landscape of the idea. John Ciardi
Tim West
Ranch Hand

Joined: Mar 15, 2004
Posts: 539
By gumbo, would you trust a guide to writing user manuals from a site named "klariti"?

What a tragic name :-\


-Tim

[Edit: OK, I had a quick look at it...it isn't contain anything terrible, but nothing particularly profound either]
[ July 04, 2005: Message edited by: Tim West ]
Aj Mathia
Ranch Hand

Joined: Apr 11, 2003
Posts: 478
Originally posted by Tim West:
What a tragic name :-\



In some parts of the world a name like Tim West would sound even more tragic
:roll:

But I sure dont agree with them
Bill Goldsworthy
Greenhorn

Joined: Dec 21, 2004
Posts: 27
Get End user feedback and listen to them.

Pretty often , imho, it's the obvious 'given' entity that we don't even bother explaining which will stump the new user the hardest.

Make it simple, but no simpler.. right?


Increasingly, people seem to misinterpret complexity as sophistication, which is baffling - the incomprehensible should cause suspicion rather than admiration. Possibly this trend results from a mistaken belief that using a somewhat mysterious device confers an aura of power on the user. Niklaus Wirth
 
permaculture playing cards
 
subject: How to write efficient User Guide...
 
Similar Threads
How to interpret userguide requirements correctly?
Do I need a special user-guide document file?
servlet shoppincart
i need to write a function that creates a XMLHttpRequest .
Should I write user guide for server mode?