Win a copy of Mesos in Action this week in the Cloud/Virtualizaton forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

How to write efficient User Guide...

 
ankur rathi
Ranch Hand
Posts: 3830
  • Mark post as helpful
  • send pies
  • 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.
 
Jeroen Wenting
Ranch Hand
Posts: 5093
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Don't put too much meaningless drivel in it
 
R K Singh
Ranch Hand
Posts: 5384
  • Mark post as helpful
  • send pies
  • 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.
 
Ernest Friedman-Hill
author and iconoclast
Marshal
Pie
Posts: 24211
35
Chrome Eclipse IDE Mac OS X
  • Mark post as helpful
  • send pies
  • 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.
 
Aj Mathia
Ranch Hand
Posts: 478
  • Mark post as helpful
  • send pies
  • 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
 
Stan James
(instanceof Sidekick)
Ranch Hand
Posts: 8791
  • Mark post as helpful
  • send pies
  • 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.
 
Tim West
Ranch Hand
Posts: 539
  • Mark post as helpful
  • send pies
  • 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
  • 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
 
Bill Goldsworthy
Greenhorn
Posts: 27
  • Mark post as helpful
  • send pies
  • 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?
 
Consider Paul's rocket mass heater.
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic