• 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

How to write efficient User Guide...

 
Ranch Hand
Posts: 3852
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.
 
Ranch Hand
Posts: 5093
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Don't put too much meaningless drivel in it
 
Ranch Hand
Posts: 5399
1
Spring Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.
 
author and iconoclast
Posts: 24207
46
Mac OS X Eclipse IDE Chrome
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.
 
Ranch Hand
Posts: 478
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
a search in google popped this which looks quite ok
http://www.klariti.com/technical-writing/User-Guides-Tutorial.shtml
 
(instanceof Sidekick)
Posts: 8791
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.
 
Ranch Hand
Posts: 539
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 478
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

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
 
Greenhorn
Posts: 27
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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?
 
reply
    Bookmark Topic Watch Topic
  • New Topic