Admittedly, writing a manual will never be confused with creating great literature. After all, a manual is all about details and processes, not plots and characters. However, good writing is good writing no matter what the subject and it is up to writers to enhance the clarity and readability of even the most narrow technical topics.
That said, if you are having difficulties with getting your manual-writing project on-track, review the postings on "Writing & Editing" and "Technical Writing". Also, check out the appropriate links listed in the "Links" Section of this site to help you get started.
In the previous postings on this topic, it was stressed that putting together an effective manual is a formidable job for any writer. But as with most Business Writing Projects, we are talking about "Process". And although a Business Communicator may not necessarily author an entire manual, he or she will often be responsible for managing the writing process.
In real terms, this means coordinating and monitoring the following steps of the manual writing project:
* Determining Style and Format
* Identifying Resources
* Developing an Outline
* Preparing A Working Draft
* Reviewing and Refining
* Getting Approvals
* Finalizing and Publishing
Granted, each step of the above process can be a minefield of organizational politics and frustration for the writer, but the intent is not to over-simplify things. Instead, the aim is to provide the writer with a straight-forward starting point for developing and writing most common office manuals.
With this in mind, here are ten tips for writers to consider as they advance through the manual writing process:
1. Do not assume or presume common knowledge.
2. Write for potential users, not content experts.
3. Edit for clarity by eliminating vague and imprecise language.
4. Define terms or include a glossary.
5. Include an index. Make subjects easy to find.
6. Use varying fonts, colors, and bullets to add visual interest to text.
7. If illustrations are to be included, have them done professionally.
8. Ensure selected users and content experts critique drafts.
9. Build in a review and update schedule for the manual.
10. If none exists, set up a system for disseminating manuals and updates.
Jack
Showing posts with label Technical Writing. Show all posts
Showing posts with label Technical Writing. Show all posts
Monday, February 1, 2010
Monday, January 25, 2010
Tips For Writing Manuals And Procedures
It goes without saying that developing an effective manual takes many skills. Writing clearly and succinctly is obvious, but Organizational, Project, Analytical, and Interpersonal Skills are just as important.
The upshot is that developers need to tap into all of their skills and talents if they want to create references that are both definitive and useful.
As with most Business Writing, developing a manual is a process, and if you learn to view the task in this manner, it becomes much more manageable. Thus, start by reviewing the basic steps for drafting manuals and procedures.
THE PROCESS
(1) Determine Style and Format
Use existing manuals as your model. If none exist, then work to get a consensus on what format will work for your organization.
(2) Identify Resources
Start with a review of possible existing manuals or Standard Operating Procedures. If starting from scratch, research authoritative outside resources, such as government regulations, technical specifications, and professional associations for industry-specific standards.
Next, interview appropriate internal specialists who may have substantive and detailed knowledge of the particular subject.
(3) Develop an Outline
Organize each section of the manual by subject. In many cases, these subjects will serve as the chapters or sections of the manual. From here, take each chapter in turn and develop a preliminary outline.
Don't obsess with being too fine at this point, as refinements will be constant throughout the process.
(4) Prepare a Working Draft
Expand your outline into a rough draft. If you are describing a process or procedure, be as detailed as you can. Also be prepared to list terminology, equipment, and materials.
If illustrations are to be included, rough these out or reserve space for their later inclusion.
(5) Review and Refine
Once you review the draft for style and readability, you will need to have it reviewed for accuracy and completeness. In many cases, this will mean using content experts.
Of course, these experts should have already been identified in the "Identify Resources" step.
(6) Get Approvals
This step in the process can be the most lengthy and frustrating. Be prepared for disagreements and bottlenecks.
The writer can try to anticipate this by factoring in additional time, but in the end, it will still fall on the writer to manage the project by keeping things on track and on deadline.
(7) Finalize and Publish
After all the revisions and rewrites are completed, the manual needs to be thoroughly proofed, then assembled. This is also a good time to set up a review and update schedule for the manual.
Things change rapidly so, in order to keep the manual up-to-date, an annual review is recommended, as a minimum.
TYPES OF MANUALS
The next step is to determine what type of manual you are writing. There are many types for sure, and each type varies greatly with respect to organization, subject matter, and the intended users.
Some of the more common manuals an internal writer may be asked to develop include the following:
Written Instructions
For the most part, writing instructions is a fairly straightforward exercise, but it is not as simple a task as it would appear on the surface. As an example, consider the simple task of frying an egg. If asked, most people would describe this task in five or six steps. But if you were outlining this task for instructional purposes, you should come up with dozen or more specific steps.
This demonstrates a universal problem with writing instructions, i.e., a writer's familiarity with a particular process or procedure can lead to the omission of important details. As such, writers need to remember that the writing of effective instructions is all about the details, so "think small".
Policies & Procedures
Policies govern how the company is to be run, i.e., they outline "what to do" under normal operating conditions. On the other hand, Procedures document step-by step processes, or "how to do it", and can include everything from paying a bill to hiring a new employee.
An established business will usually organize their Policies and Procedures into a formal Policy and Procedures Manual, with each section of the manual detailing a specific function or operation.
Sometimes Policies and Procedures exist as separate manuals, but it is very common to combine the two. Regardless, policies are always the governing authority, and care must be taken to ensure that written procedures comply and reinforce this authority.
Standards & Guidelines
Most established companies, whether large and multi-national or small and local, attempt to set standards for their products, services, or personnel. And these can cover anything from production quotas, to quality control, to dress and conduct.
Standards are usually measurable and non-negotiable benchmarks. On the other hand, Guidelines, while not necessarily mandatory or as stringent as Standards, are designed to provide employees and managers with suggestions and rationales for dealing with certain situations or job processes.
In some organizations, Standards and Guidelines are included with policies and procedures, while in other companies, they are compiled as separate manuals and organized in a variety of ways, such as by department, process, or job. Either way is acceptable and generally depends on organizational custom and preference.
Operations & Service Manuals
Operations Manuals detail the resources and processes required for a function or department to complete its mission. And these types of manuals can cover every department within an organization, from Administration to Manufacturing
Another type of manual that is often combined with an Operations manual is the Service Manual. As the name suggests, this type of manual is primarily associated with the maintenance and troubleshooting of systems and equipment.
It should be noted that Service Manuals are often written and updated by outside vendors and technical specialists. Even so, the internal writer should still ensure these manuals adhere to the same style and readability of internally-produced communications.
User & Reference Manuals
It's a given that learning to use all the features of software, hardware, or other business tools, invariably involves "looking things up". And this usually means diving into a User and Reference Manual.
User Manuals, as the name suggests, are written for primary users or operators. They usually describe the basic operations of a particular piece of software or hardware - from installing a program, to the minor care and servicing of equipment.
Reference Manuals are much more detailed than User Manuals. They are usually written for experts and technical specialists, so they will often contain such information as software codes, hardware specifications, detailed troubleshooting, and contact information.
Training Manuals
A formal Training manual is an expansion and refinement of the "Written Instructions" presented earlier in this article. These types of manuals can be designed as self-paced learning tools, on-the-job training guides, or as companion texts for seminars.
By and large, Training Manuals are designed to present, detail, and reinforce new concepts or processes. Usually organized by "Units", the most effective Training Manuals are those that provide trainees with basic information, upon which more advanced skills and competencies are introduced through practice on real-life scenarios.
For the writer, designing and packaging an effective Training Manual is a two-step process.
In the design stage, it starts with coordinating and working with content experts. Simply put, these experts will provide the writer with the raw material for the manual. From here, it is a matter of "Instructional Design".
Ideally, this should be left up to a Training Professional or Instructional Designer. In larger organizations this expertise may be available in-house, but in many smaller companies, it is often left up to an internal writer to muddle through this task.
If this is your situation, then you should look into using an outside specialist. If this is not possible, you should, at the very least, research the many desktop and online resources available on this subject.
Packaging is the second step in putting together a Training Manual. Basically, this step addresses the format, style, clarity and readability from a creative or marketing perspective.
Simply stated, if you want employees to use a Training Manual, or any manual for that matter, it will have to be visually appealing and easy to use. In this regard, don't be afraid to exercise your creative talents. Be mindful that learning may not always be fun, but it shouldn't be completely dry and lifeless either.
On line Manuals
On line Manuals have several advantages over printed versions. The obvious pluses are they are easier to keep current, and are more readily accessible to remotely located users than traditional bound volumes.
Of course, an effective On line Manual requires additional features that are not part of a printed version. For example, a keyword search capability, and "links" to other manuals or sources are two features that have become pretty much standard and expected of digital documents.
For writers not adept at "Interactive Learning" or "Web Design", this means learning new skills or enlisting the help of others (from either inside or outside of the organization) who do possess these skills.
A Few Final Words
In the end, all manuals, regardless of type, need to be comprehensive, up-to-date, and "user-friendly". Anything less will be largely ignored. A writer tasked with developing a manual has an opportunity to create an enduring and valuable resource for their organization. That said, why not embrace the challenge and do the the job correctly?
Related Links:
http://writershelper.com/instruction-manuals.html
http://en.wikipedia.org/wiki/Instructional_design
http://www.webdevelopersjournal.com/articles/convert_documents.html/
http://www.useit.com/papers/webwriting/
Jack
The upshot is that developers need to tap into all of their skills and talents if they want to create references that are both definitive and useful.
As with most Business Writing, developing a manual is a process, and if you learn to view the task in this manner, it becomes much more manageable. Thus, start by reviewing the basic steps for drafting manuals and procedures.
THE PROCESS
(1) Determine Style and Format
Use existing manuals as your model. If none exist, then work to get a consensus on what format will work for your organization.
(2) Identify Resources
Start with a review of possible existing manuals or Standard Operating Procedures. If starting from scratch, research authoritative outside resources, such as government regulations, technical specifications, and professional associations for industry-specific standards.
Next, interview appropriate internal specialists who may have substantive and detailed knowledge of the particular subject.
(3) Develop an Outline
Organize each section of the manual by subject. In many cases, these subjects will serve as the chapters or sections of the manual. From here, take each chapter in turn and develop a preliminary outline.
Don't obsess with being too fine at this point, as refinements will be constant throughout the process.
(4) Prepare a Working Draft
Expand your outline into a rough draft. If you are describing a process or procedure, be as detailed as you can. Also be prepared to list terminology, equipment, and materials.
If illustrations are to be included, rough these out or reserve space for their later inclusion.
(5) Review and Refine
Once you review the draft for style and readability, you will need to have it reviewed for accuracy and completeness. In many cases, this will mean using content experts.
Of course, these experts should have already been identified in the "Identify Resources" step.
(6) Get Approvals
This step in the process can be the most lengthy and frustrating. Be prepared for disagreements and bottlenecks.
The writer can try to anticipate this by factoring in additional time, but in the end, it will still fall on the writer to manage the project by keeping things on track and on deadline.
(7) Finalize and Publish
After all the revisions and rewrites are completed, the manual needs to be thoroughly proofed, then assembled. This is also a good time to set up a review and update schedule for the manual.
Things change rapidly so, in order to keep the manual up-to-date, an annual review is recommended, as a minimum.
TYPES OF MANUALS
The next step is to determine what type of manual you are writing. There are many types for sure, and each type varies greatly with respect to organization, subject matter, and the intended users.
Some of the more common manuals an internal writer may be asked to develop include the following:
Written Instructions
For the most part, writing instructions is a fairly straightforward exercise, but it is not as simple a task as it would appear on the surface. As an example, consider the simple task of frying an egg. If asked, most people would describe this task in five or six steps. But if you were outlining this task for instructional purposes, you should come up with dozen or more specific steps.
This demonstrates a universal problem with writing instructions, i.e., a writer's familiarity with a particular process or procedure can lead to the omission of important details. As such, writers need to remember that the writing of effective instructions is all about the details, so "think small".
Policies & Procedures
Policies govern how the company is to be run, i.e., they outline "what to do" under normal operating conditions. On the other hand, Procedures document step-by step processes, or "how to do it", and can include everything from paying a bill to hiring a new employee.
An established business will usually organize their Policies and Procedures into a formal Policy and Procedures Manual, with each section of the manual detailing a specific function or operation.
Sometimes Policies and Procedures exist as separate manuals, but it is very common to combine the two. Regardless, policies are always the governing authority, and care must be taken to ensure that written procedures comply and reinforce this authority.
Standards & Guidelines
Most established companies, whether large and multi-national or small and local, attempt to set standards for their products, services, or personnel. And these can cover anything from production quotas, to quality control, to dress and conduct.
Standards are usually measurable and non-negotiable benchmarks. On the other hand, Guidelines, while not necessarily mandatory or as stringent as Standards, are designed to provide employees and managers with suggestions and rationales for dealing with certain situations or job processes.
In some organizations, Standards and Guidelines are included with policies and procedures, while in other companies, they are compiled as separate manuals and organized in a variety of ways, such as by department, process, or job. Either way is acceptable and generally depends on organizational custom and preference.
Operations & Service Manuals
Operations Manuals detail the resources and processes required for a function or department to complete its mission. And these types of manuals can cover every department within an organization, from Administration to Manufacturing
Another type of manual that is often combined with an Operations manual is the Service Manual. As the name suggests, this type of manual is primarily associated with the maintenance and troubleshooting of systems and equipment.
It should be noted that Service Manuals are often written and updated by outside vendors and technical specialists. Even so, the internal writer should still ensure these manuals adhere to the same style and readability of internally-produced communications.
User & Reference Manuals
It's a given that learning to use all the features of software, hardware, or other business tools, invariably involves "looking things up". And this usually means diving into a User and Reference Manual.
User Manuals, as the name suggests, are written for primary users or operators. They usually describe the basic operations of a particular piece of software or hardware - from installing a program, to the minor care and servicing of equipment.
Reference Manuals are much more detailed than User Manuals. They are usually written for experts and technical specialists, so they will often contain such information as software codes, hardware specifications, detailed troubleshooting, and contact information.
Training Manuals
A formal Training manual is an expansion and refinement of the "Written Instructions" presented earlier in this article. These types of manuals can be designed as self-paced learning tools, on-the-job training guides, or as companion texts for seminars.
By and large, Training Manuals are designed to present, detail, and reinforce new concepts or processes. Usually organized by "Units", the most effective Training Manuals are those that provide trainees with basic information, upon which more advanced skills and competencies are introduced through practice on real-life scenarios.
For the writer, designing and packaging an effective Training Manual is a two-step process.
In the design stage, it starts with coordinating and working with content experts. Simply put, these experts will provide the writer with the raw material for the manual. From here, it is a matter of "Instructional Design".
Ideally, this should be left up to a Training Professional or Instructional Designer. In larger organizations this expertise may be available in-house, but in many smaller companies, it is often left up to an internal writer to muddle through this task.
If this is your situation, then you should look into using an outside specialist. If this is not possible, you should, at the very least, research the many desktop and online resources available on this subject.
Packaging is the second step in putting together a Training Manual. Basically, this step addresses the format, style, clarity and readability from a creative or marketing perspective.
Simply stated, if you want employees to use a Training Manual, or any manual for that matter, it will have to be visually appealing and easy to use. In this regard, don't be afraid to exercise your creative talents. Be mindful that learning may not always be fun, but it shouldn't be completely dry and lifeless either.
On line Manuals
On line Manuals have several advantages over printed versions. The obvious pluses are they are easier to keep current, and are more readily accessible to remotely located users than traditional bound volumes.
Of course, an effective On line Manual requires additional features that are not part of a printed version. For example, a keyword search capability, and "links" to other manuals or sources are two features that have become pretty much standard and expected of digital documents.
For writers not adept at "Interactive Learning" or "Web Design", this means learning new skills or enlisting the help of others (from either inside or outside of the organization) who do possess these skills.
A Few Final Words
In the end, all manuals, regardless of type, need to be comprehensive, up-to-date, and "user-friendly". Anything less will be largely ignored. A writer tasked with developing a manual has an opportunity to create an enduring and valuable resource for their organization. That said, why not embrace the challenge and do the the job correctly?
Related Links:
http://writershelper.com/instruction-manuals.html
http://en.wikipedia.org/wiki/Instructional_design
http://www.webdevelopersjournal.com/articles/convert_documents.html/
http://www.useit.com/papers/webwriting/
Jack
Monday, January 18, 2010
Developing Manuals and Procedures: Getting Started
Developing Manuals and Procedures is a very labor-intensive process, as well as a challenging and daunting project for anyone facing this task.
The ability to write clearly and succinctly is obvious, but Organizational, Project, and Analytical Skills are just as important. And let’s not overlook the interpersonal challenges, where everything from company politics to "luke-warm" cooperation can derail the development process at the onset.
The upshot is that writers need to tap into all of their skills and talents in order to do the job properly.
Manuals and Procedures are written to cover just about every facet of an organization, from rules and regulations to processes and procedures. That said, writers need to first decide what type of manual is to be written. Thus, begin by asking the following questions:
* What is the scope of the manual? (company-wide or departmental)
* Is the manual detailing rules or operating procedures?
* Will the manual be used for reference or training purposes?
How you answer these questions will help determine the type of manual you will be writing. There are many types, but most will generally fall under one or more of the following categories: Policy, Procedures, Standards, User, Reference, Training, Operator, and Service.
For the writer, it is important to remember that each of these types have different purposes and objectives, and each varies with respect to organization, content, and detail.
Another consideration at this early stage is to decide whether the manual will serve a single or multiple purpose. While each of these above types can exist as stand-alone manuals, in many organizations they are often combined. Some of the more common examples are:
* Policy and Procedures
* Standards and Guidelines
* Operations and Service
* User and Reference
In many cases it makes perfect sense to group two or more related types of manuals for efficiency, productivity, and easy reference. But how you do it will often be determined by organizational custom and the needs and wants of the intended users.
Once you have answered the above questions, you can begin the writing process in earnest. The basic steps are as follows:
* Determining Style and Format
* Identifying Resources
* Developing an Outline
* Preparing a Working Draft
* Editing and Proofing
* Getting Approvals
* Finalizing and Publishing
The next Posting will expand on these steps as well as outline the function and format of the more common types of Manuals and Procedures used in Business Organizations.
Jack
The ability to write clearly and succinctly is obvious, but Organizational, Project, and Analytical Skills are just as important. And let’s not overlook the interpersonal challenges, where everything from company politics to "luke-warm" cooperation can derail the development process at the onset.
The upshot is that writers need to tap into all of their skills and talents in order to do the job properly.
Manuals and Procedures are written to cover just about every facet of an organization, from rules and regulations to processes and procedures. That said, writers need to first decide what type of manual is to be written. Thus, begin by asking the following questions:
* What is the scope of the manual? (company-wide or departmental)
* Is the manual detailing rules or operating procedures?
* Will the manual be used for reference or training purposes?
How you answer these questions will help determine the type of manual you will be writing. There are many types, but most will generally fall under one or more of the following categories: Policy, Procedures, Standards, User, Reference, Training, Operator, and Service.
For the writer, it is important to remember that each of these types have different purposes and objectives, and each varies with respect to organization, content, and detail.
Another consideration at this early stage is to decide whether the manual will serve a single or multiple purpose. While each of these above types can exist as stand-alone manuals, in many organizations they are often combined. Some of the more common examples are:
* Policy and Procedures
* Standards and Guidelines
* Operations and Service
* User and Reference
In many cases it makes perfect sense to group two or more related types of manuals for efficiency, productivity, and easy reference. But how you do it will often be determined by organizational custom and the needs and wants of the intended users.
Once you have answered the above questions, you can begin the writing process in earnest. The basic steps are as follows:
* Determining Style and Format
* Identifying Resources
* Developing an Outline
* Preparing a Working Draft
* Editing and Proofing
* Getting Approvals
* Finalizing and Publishing
The next Posting will expand on these steps as well as outline the function and format of the more common types of Manuals and Procedures used in Business Organizations.
Jack
Subscribe to:
Posts (Atom)