Manuals

I am still in the mess of creating the right document. There have been too many confusing definitions comming in. Here is how I have classified them...

Visio Stencil for UML

Note:
Visio Stencil for UML.. makes it really simple to use. no metadata to fill up if you dont want to.. just stick to visual representation.

http://www.softwarestencils.com/uml/index.html

Can a system generate User Manual

Can any software generate an User Manual?
I think no..
I am having a tough time convincing my project managers and directors. Sometimes Vendors sell their products as a silver bullet to everything. Telelogic was no different. But what makes it worse is that conceptually it has all the elements required to make an User Manual. I am talking about System Architect from Telelogic that my client is using at this moment.

Here is how the logic goes:

1- The "Business Requirement Document" has the process flows. There have activities and tasks atttached to them. They also tell you the actors/roles involved in doing an activity
2- The SRS has the Use Cases and thus the exact flow defining how the actor is going to interact with the system
3- The User Interface Specification Document has the Screenshots of the User Interfaces. This has the description of all the fields on each screen
4- The test cases have a description of the various scenarios, each talking of the steps and the expected results.

So you see, it's all there (SA keeps all these in the form of an encyclopedia)...The User Manual just consists of these things. So you should be able to generate it.

The problem is what gets generated is of no good as an User Manual. It still looks as a technical document. I am sure the users would not even touch it. The language, the presentation, the organisation .. it's all wrong...

Well this episode is yet to finish. I wish to see how it turns out...

Making a User Manual

I had a task to this week, that I had never tried before. I had to finalize the template for an User Manual. 5mins into the meeting and I could pick out 3 words being tossed around interchangeably and each one infering what he feels like. These were "User manual", "Operations Manual", "SOP". I had to stop all discussions untill I ensured we were all clear about these words. We agreed that "USer Manual" is the same as Operations Manual and that is what we are going to develop.

One more meeting and I had people breaking their heads over what I had considered would be a simple task. Anyway, I thought of doing a bit of homework and borrow from some of the thought leaders. Here are excerpts from some of the interesting articles that I came across and links to them. However I keep the url of the article I liked most to the end.

----------------------------------------------------------------------------
http://www.asktog.com/columns/017ManualWriting.html
Tips that I liked from this article
1) Explain the problem being solved
2) Present the concepts, not just the features.

Technical writing is disctinctly different from literary writing in the sense that "It's not about telling a story or expressing your thoughts or feelings. Organization, layout, simplifying complex concepts, explaining why and how to do things, and identifying with users on their own terms are much more important than finesse with language."
-----------------------------------------------------------------------------
http://www.klariti.com/technical-writing/User-Guides-Tutorial.shtml

Chunking text

Breaking large pieces of information into smaller piece of information is called "chunking."

When writing user guides, you can separate information by menu options and their respective consequences, for example, showing the user the results of each action.

------------------------------------------------------------------------------
http://greatdocuments.net/how-to-write-a-user-guide/
Three. Divide and conquer. Look into the overall architecture of the system, and divide your manual in the same way. Do not try to reinvent the wheel. Does a pilot fish become the shark? Never…he just follows and gets his meal that way. As you follow the Architecture of the system, this will ease your documentation efforts greatly. People will follow your documentation in a way that is parallel to the system itself.
-------------------------------------------------------------------------------
http://www.writershelper.com/instruction-manuals.html
Instruction Manuals Writing Tip #5: Use formatting to clarify your messageInstruction Manuals Writing Tip #8: Answer your readers' questions They will be asking what, when, where, how and sometimes who and why?
Instruction Manuals Writing Tip #10: Test the instructions
--------------------------------------------------------------------------------

The article that I like best (may be because it fitted my immediate needs) was:
http://www.devshed.com/c/a/Practices/Writing-A-User-Manual-part-2/
http://www.devshed.com/c/a/Practices/Writing-A-User-Manual-part-1/

The TOC i finally came up with, finally looks something like this

Title page
Document Control
Contents
Introduction
	Purpose	This section explains the high level objectives this document is intended to serve.
	Intended Audience	This section lists various audience groups or individuals that would be interested in the information contained in the document.
	Conventions	Any specific conventions used in the document are described in this section. This would help the target audience to understand the content of this document in a structured manner.
	Definition, Acronyms and Abbreviations	The following points represent Any definitions, acronyms and abbreviations used in the document are listed here along with their descriptions.
	Related Documentation	This section lists any other documents (versioned) that may have been referred to in whole or in part by this document. Any documents used in the preparation of the user may also be listed here.
	Document Organization	This section describes the structure of the document outlining the relevance and objectives of each chapter.
System Overview
	Overview	General description of what the system does
	Subsystems	List of sub-systems/modules if any
	System Capabilities	What it does and does not do (list the exact tasks)
	System Roles/Actors Vs Tasks	1- User levels and the implications 2- Tasks/activities that can be carried out by each user
System Task 1..n
	Overview	The goal/purpose or output
	UI	Screenshot
	UI elements	Table (Field label, Description/Type, Inputs/Actions)
	Task instructions	Step wise instuction to achieve desired output
Appendix		All peripheral information that would be detracting when given in the main body. Detailed diagrams, flow charts, or references to other documentation should be put here
	Information model
	Process Flow
	Error Messages
	Troubleshooting
	etc..