File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
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
JavaRanch » Java Forums » Other » Meaningless Drivel
Bookmark "How to write efficient User Guide..." Watch "How to write efficient User Guide..." New topic

How to write efficient User Guide...

ankur rathi
Ranch Hand

Joined: Oct 11, 2004
Posts: 3830
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

R K Singh
Ranch Hand

Joined: Oct 15, 2001
Posts: 5382
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

Joined: Jul 08, 2003
Posts: 24199

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

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 :-\


[Edit: OK, I had a quick look at 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

But I sure dont agree with them
Bill Goldsworthy

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
I agree. Here's the link:
subject: How to write efficient User Guide...
It's not a secret anymore!