Author: Theresa Pojuner

A Standard Operating Procedure (SOP) contains a list of steps or directions to follow for accomplishing a particular task. It is a set of approved guidelines consisting of steps that have to be followed from inception to completion. Having an SOP standardizes tasks and eliminates confusion about particular tasks.

Up front, an SOP contains the same information as Business Requirements (with the Scope and Purpose) and ends with information as if you were writing Functional Specifications (Glossary, Appendix). Begin with the purpose of the document and include who authorized, approved, and formulated the SOP. (It is a good idea to include the people who will be affected in brain storming sessions when the standards are beginning to be developed.) Within the scope of the SOP for a, e.g., product, describe what the procedure entails, list any other products, departments, etc. that are involved, and the history behind it. While writing, simultaneously begin to include a section at the end for an Appendix for Company Policies as well as a Glossary section for definitions or terminology as these can become difficult to grasp depending on the industry you are writing for. Pharmaceutical, Financial, or Insurance institutions for example, have a wide range of terminology which the average person may not be familiar with.

An example of an SOP for:

• System managers are the steps needed to perform backups, system recovery, start-up, shut-down, performance monitoring, notifications, etc.
• Developers are the steps involved when producing an application through its complete development life cycle, creating prototypes, etc.
• Retailers are the steps involved for handling inventory, returns, losses, layaways, etc
• Pharmaceutical manufacturing are the steps for clinical trials, adverse effects, data collection, regulatory requirements, etc.
• Insurance claims are the steps for policies, appraisals, reinsurance, settlements, etc.
• Accountants are the steps involved in payroll, disbursement of funds, inventory, purchases, receipts, etc
• Testers are the steps involved within test plans, test cases, system acceptance criteria, etc

SOP’s should also include the following:

• People involved/affected
• Responsibilities and consequences
• Quality control to ensure tasks have been correctly completed
• Check lists to ensure all tasks have been completed
• Instructions for revising the SOP to ensure up-to-date accuracy
• List of requirements to accomplish a task
• Illustrations if needed
• Table of Contents
• Appendix
• Glossary

Having Standard Operating Procedures eliminates guess work and helps in creating quality work. They answer questions and clarify answers. It is not easy to develop an SOP, but if you are a curious person, then you will have no problem in gathering information to create one. And always remember to write for your target audience and be concise and to the point in explanations.

How do you get information to document when there is resistance? One of the many reasons comes from not understanding the importance of documentation. There are also those who are not used to having documentation. They were trained by others so why waste time to put it down on paper? They do not understand the need for it nor why you want to know. They need to understand that documentation is way of archiving information.

How do you get others to share information?

You need to identify with them and acknowledge their fears and questions and make sure they understand you are there to document procedures and processes so that no knowledge is lost and that ownership is recognized and that no consequences will occur because of inaccuracies.

What if they are hesitant because some of the information they give you may not be correct?

Let the information providers know that their knowledge is needed for company improvements and growth. Assure them that everything will be double checked to ensure that what is written by the writer is correct and that any inaccuracies will be on the writer and not the respondent. Assist them by first coming up with an outline or a diagram or flow chart and then have them help you fill in the blanks or make changes.

There are those also, who worry about job security. Are you going to use it against me?

Be aware of how they perceive you. During a meeting you could compliment them for a task or for some knowledge that they did impart to you. Show them you respect them for their knowledge and that you are only there to learn and nothing more.

What if they feel as if you want to change the process that they began and you want to take their ownership away and reduce their status?

Assure them that you’re just documenting processes so that no one will veer from their original procedure and that they are respected for their knowledge. Ask them questions, such as how they think a process could be improved or what they think are the current benefits and drawbacks. Make them feel important.

Sometimes it’s because they just don’t like to answer questions. How can you meet with them if they are always busy?

Analyze the situation, listen, and decide on the best approach to take for meeting with them. While getting coffee, ask how their day is going, be interested in them, and try to find some common ground. Try using the same method while walking into a meeting or while leaving work. Anytime you run into them, start up a conversation unrelated to work. Or, you could make sure your desk is near the most resistant SMEs (Subject Matter Experts).

There are many other reasons as to why you cannot get certain information. Persistence is the key and understanding the work environment is another. But no matter what they are, you have to break down those barriers and get the information you need. Treat them the way they would like to be treated or the way you would like to be treated. Also, get management to support your work and make sure they introduce you to others so that the individuals know you are there because of management.

The bottom line is you need to have an effective, direct, and everyday interaction with these individuals.

Documentation is a form of communication that allows us to share knowledge across all levels of an organizations structure, is readily available at all times, and is an essential part of a company’s best practice and improvement process. For example, through documentation, companies, employees, and clients are kept informed of business requirements for new or revamped deliverables. Information gathered from subject matter experts, from shadowing others, and from hands-on experience is explained in clearly written documents that are created for specific target audiences.

But what is the Return On Investment (ROI) of documentation? What if we didn’t have any?

Without any documentation:

• Stakeholders, clients, managers, developers, analysts, testers, etc would not have the necessary information needed to get their jobs completed with accuracy. They need technically precise information that is written in a logical and concise manner. Documentation thus breaks down highly complex models into simpler easy-to-understand concepts, processes, and procedures via workflows and content for specific targeted audiences. As an example, if test cases were not documented, Testers would not know what scenarios or scripts to work on for their user acceptance testing to ensure quality products.
• Legacy information would not be available to denote a systems structure or architecture, or to list original developers, or to communicate the knowledge for reproducing a similar system. If any developers or analysts were asked to create a similar model or project, time would be lost in researching information. They would not know, e.g., which database, platform, or system structure to use. They would have to spend time to initiate several meetings to gather all relevant information and would lose project time when all they would have had to do was refer to existing documentation. In other words, documentation saves the company time, money, and effort when processes need to be revisited.
• Guides, manuals, marketing material, etc. would not be available to pass knowledge to consumers, clients, etc. Clearly written guides and training material are needed to provide basic understanding of fundamental key processes and concepts of the end product.
• Any new users, hires, managers, developers, etc would not have the necessary resources to assist them in understanding the functionality of existing applications. Documentation walks users through various manual processes and provides best practices for using and building products.
• Information transpired during time consuming technical meetings would be lost. Documentation is gathered for a products life cycle beginning with gathering requirements to passing data to the development team, to the testing phase, and finally to production. The content can consist of anything from its purpose to resources to various platforms and architecture.

Technical Writers use documentation as a tool to help readers see and understand technical information more easily. As a rule, documentation should be part of a company’s standardization process in order to avoid reinvention and duplication of a process, application, product, report, etc. This is especially needed in large corporations where there is a lot of information spread across multifunctional divisions or departments.

There really isn’t a mathematical way that I am aware of that currently measures the ROI of documentation. We know its value by the support it provides and its accomplished goal.

If you have ideas for the ROI of documentation, please leave a comment.

Technical Writers do more than just write. They communicate relevant technical information to get jobs done; see previous posts on what a Technical Writer does (see Defining a Technical Writer). They create the documentation, but how do they present an effective and appealing document? In a previous post, we discussed how to create a Style Guide and the importance of them. The guide allows the writer to focus on writing the content, and less on the look and feel of the document. No matter which Style Guide is followed, there are certain popular generic rules that should be followed. You might say the items mentioned below, can be part of a Style Guide.

To increase the visual appeal of a document, we should adhere to certain rules the same way we do for grammar. If the document is too long, does not present any illustrations, and is strictly text, the user will have a problem just reading the first page. Readers will usually flip through the document to see how it is structured. If it has a lot of white space, images, and has varying styles and formats, then viewers will more likely read it. Apply some of the following tips:

• Insert images; use plenty of graphics; snapshots, tables, and charts to aid in explanations.
• Use pointers, callouts, or arrows pointing to each part of an active item.
• Organize document with easy to find information; use plenty of pointers, references, tips, thumbnails, etc to guide the reader.
• Make paragraphs short and succinct; use simple words and write for the audience.
• Use icons indicating relevant-must know information; warnings, advice, rules, policies, etc.
• Ensure plenty of white space.
• Do not create lengthy documents; break it up into more than one.
• Limit varying fonts and colors for pointing out information.
• Use outlines, bullets, etc., for ease of readability.
• Apply headers and footers.
• Include Glossary, Table of Contents, Appendix, Index, Error section, Check List, or Reference sheet/card if applicable.
• Include a Q&A section.
• When instructing, create numerical step-by-step directions and include indented sub-levels if appropriate.
• Change up the style from one section to another, e.g., from one column to two, or have text flow around images for a change.

Try to create a visually appealing document using some of the above ideas. If you have more suggestions or ideas on how to make documentation more appealing, please leave a comment.

There are quite a lot of questions about how a document should be designed. If the document projects an appealing appearance and motivates the user to want to read it, then the document has been properly designed. But how do we do this? A lot of these questions can be answered within a Style Guide. It will outline familiar or commonly used styles and formats that users have previously agreed upon. The amount of content presented in a Style Guide will depend on what is required for each document to be created.

• Try to denote only the important ‘must have’ items within the Style Guide.
• If it becomes too lengthy, break it up into sections and include a Table of Contents. It might even be more logical to break it up into more than one document. For example, if the:
  • Style Guide is for Developers, you might create two different guides. Create a Style Guide for a document that details the format to use when requesting, compiling, and logging database changes and another Style Guide showing what style to use for coding documentation.
  • Style Guide is for HR, you might need to create several, such as a guide for a document explaining how to complete certain forms, another guide for a document that explains procedures to follow, and another guide that explains the style to use when writing about company policies.
  • Keep it organized; break up the guide by sections or subject matter.

What and how many Style Guides you create depends on the document type, project type, etc.

To help you begin, try to:

• Go back and track down previous documents and see how they were written and see what format was used the most. Also, note down inconsistencies.
• Create a chart to help you stay organized; use headers indicating various types of documentation versus the formatting and style used. Use this chart to give you an overview of what currently exists. Use it to also see where you can make the existing documentation more organized and efficient.
• Have a meeting with managers, project leaders, developers, users and those that will be using the Style Guides. Inform them of the Style Guides you will be creating and present examples.
  • Communicate to them that each document created should have their own Style Guide.
  • If you already have a draft of each type of guide, have them examine each one and then give a quick synopsis and see if they approve or disapprove of them.
  • Show them the chart you created, point out the inconsistencies, and indicate how you came to the decisions you arrived at for creating better documentation.
  • Explain how a Style Guide would allow a writer to focus on the topic and would save time and energy, as the writer does not have to think about how to format or style a document.
  • You might face some opposition. They may want to keep some of the old formats and disagree with you. Listen to them, find out what they want and give them what they want. If you can, include what is desired, but indicate this as an exception.

This meeting is where you lay out all questions, uncertainties and reservations onto the table. This is the time to get all your answers. Also, if you have a pressing issue, ask it now. After the meeting, forward all attendees updated Style Guides to see if they meet with their approval.

Do not be discouraged. What will be in the company Style Guides will depend on the company and its culture.

If you have used Style Guides or created them, and would like to share some ideas for them, please leave a comment

When putting together a document, where do you begin? What formatting or style do you use to present and communicate your information in a document? This question and others can be answered within the Style Guide. A Style Guide contains a set of rules that a writer uses to maintain consistency for grammar, format, and or content material. There are several Style guide designs. There is usually a generic guide that gives a summary of what styles and formats to use for particular types of manuals and then there is a more specific guide with greater detail, i.e., for:

• Medical and Science Writers when submitting regulatory documentation or research,
• Developers when submitting requests for database changes and documenting code,
• Engineers who require Functional Specifications and Technical Specifications,
• Testers who require QA specifications,
• Users who require User guides and Reference sheets documenting processes and definitions,
• HR Personnel when writing procedural instructions or educational material, or
• Manufacturers when creating design specifications, etc.

These were just a few examples. Following a written set of guidelines ensures that the document is consistent, uniform, and allows the writer to focus on the writing of the material. You can call it a blueprint or template to follow. It will help the writer design the finished product and it will also make it easier for the reader, because they’ll know beforehand where certain information is located within a document because of the consistent style.

The Style guide will also:

• Detail grammar and industry terminology.
• Denote how certain text would be displayed within, e.g., Medical specifications or descriptions, or database definitions.
• Indicate how to display numbers, or how to present abbreviations, i.e., should they be presented with initial caps or are some initial caps and some lower case?
• How to format other objects such as check boxes or bullets or drop down lists.
• Show where objects are defined. Should, e.g., definitions be placed in the back of the document, before the glossary or within the Appendix? How should tables be formatted and laid out? Should a background color be applied to the table or should only the heading have a background color?
• Note what typeface, font, and size should be used. Will a newspaper or column style be applied and should text always be left justified?
• Indicate the type of graphics embedded; are only jpeg files permitted or are any types of graphic files permitted?

Many other groupings or items have to be described as well, such as the Table of contents, the Appendix and headers and footers and paragraph breaks.

Most Style Guides contain references to sample material, standard conventions, a glossary, etc. So I guess the answer to the question ‘Do we need a Style Guide’ is ‘Yes’.

Note: As reminder, as with all documents, include a section for the review cycle and sign off sheets. This will ensure that everyone approves of the particular Style Guide. See some tips in the next post.

To make it easier for some users to remember and/or to have access to pertinent information quickly, Ready Reference Sheets are created. Ready Reference Sheets are a useful collection of convenient and relevant information on a sheet of paper, a single page of a document, or on a card. They can contain anything from a brief overview of a program, a brief description of various functions, to just quick ways to accomplish a task. There is a gamut of uses for them.

Ready Reference Sheets can contain a list of items or functions that a program can perform, or a list of necessary instructions to accomplice a task. Each sheet can contain:

• a chart of function keys and their purpose,
• a quick set of instructions to perform a particular task,
• a list of required definitions or reserved names,
• a list of codes/embedded commands necessary to initiate a process, or
• a list of functions that shouldn’t be used for a program.

For the developers, it can list:

• the type of packages, procedures, and functions that can be used,
• unacceptable codes/references,
• codes used for certain projects,
• where certain project codes should be backed up and stored,
• system backup requirements,
• authorizations, or
• trouble-shooting tasks.

There is an abundance of examples:

• For reports, the reference sheet can list the commands to initiate a report, what errors might indicate, whom to notify, and how to correct certain problems.
• For a department, it might be a listing of available programs, their usage, gaining access, and even an index of cross-reference sheets.
• For a communications package, the quick reference card may contain step-by-step instructions for performing a quick installation.
• For customer service, the reference sheet might contain scenarios that are encountered and how to respond or where to refer the customer to next.
• For a quick style guide reference, the sheet can contain universal formatting styles, information required for each document, storage information, accessibility, and privileges.

The creation of Ready Reference Sheets depends on the need, demand, and usefulness for them. No matter what a Reference Sheet is created for, be sure it’s pertinent to the users. Ready Reference sheets are generally one page in length front and back and in some cases 2 pages (front and back) but really no more than 2 sheets of paper. If using cards, limit information as much as possible per card.

If you have used Ready Reference Sheets or cards for presenting information, and would like to share some ideas for them, please leave a comment.

Creating easy to read guides for users is essential for all products to succeed. With any new product, some users are reluctant to change, but if the Technical Writer can provide an easy to read, friendly, and understandable user or training guide, less resistance would be encountered. The user cannot be expected to instinctively know how to operate and use a new product. Even if the product is an updated revised version of an application, the user still needs to know what is new and why it was revised when the existing version seemed fine and workable for them.

Before beginning to write the guide, communicate with and get to know what the users current knowledge is and how they prefer to have documents presented. This way you will know whether or not to use more visuals, charts, figures, etc. The Technical Writer needs to know how the audience learns best.

After meeting with the users and learning and understanding the functionality of the, e.g., application, the Technical Writer can now begin to write the User Guide. If the User Guide is about how to run an application, include:

• Table of Contents
• Information on the product; include a bit of history
• How to operate, install, log-on, use the program
• What prompts to expect, information required, error messages
• Getting help with an FAQ section if applicable
• Trouble-shooting section
• Glossary
• Appendix with samples if needed
• Feedback section

If it is a revamped application, with a new interface, menu, etc, then in addition to the above, include:

• Pictures of the old version versus the new so that a comparison is easily visible
• Information on new processes, i.e., how to add/remove data to/from the forms or how to reset headings for a report, or how to use the new print or search procedures
• Symbols or other markers denoting new items with details

To make the User Guide more appealing and to emphasize details, include visuals such as, graphics, process flow diagrams, charts, screen shots, or images. Also, use storyboard or animation tools to aid in displaying the flow of the application or the steps leading to its functionality. If it is a complicated application or a new process, consider creating a video or presenting an instructor-led class to illustrate and provide information. Sometimes a short one sheet reference guide is all that is needed.

Note: Sometimes there is a cross-over between User guides and Training Manuals. But there is a difference between them. A Training Manual is usually provided during instructor-led classes, where the instructor can demonstrate, e.g., certain tasks. The student can then use the manual to reinforce what was taught by working through a set of exercises. Solutions would be provided as well as explanations. A quiz would also be presented at the end of each chapter/section along with explanations to help guide the student during the learning process. But no matter which one is written, the content would also include items similar to the standard User Guide discussed here.

More information on Ready Reference Sheets will be described in the next post. If you have any questions, or feel I’ve left out information or wish more information on an item, please leave a comment.

The Requirements document has been completed and approved. The next step in getting the product built according to the client’s wishes will be to create a Technical Specifications document to communicate all the technical information gathered from meetings. The document will contain detailed technical instructions and information for the development team (Developers, Engineers, Architects, and IT Managers).

Technical Specifications for most applications will include detailed data on the:

• design (look and feel) of the application,
• different data bases, constraints, tables, and platforms involved,
• images for designing and navigating through the application (i.e., graphics, process flow diagrams, data relational diagrams, charts, etc.)
• fields involved (i.e., length, numerical only, drop-down lists, check boxes, bullets),
• fonts, colors, images, or logos used (when and where),
• usage of new or reused application codes,
• types of error messages presented (when and where),
• types of security, privileges, and privacy notices to be created,
• functionality for web only, downloadable, or portable applications,
• necessary coding for static or future products,
• gathering of content,
• table of contents, glossary and appendix.

Depending on the product, the technical specification may also include detailed information on the:

• size and shape of a new, redesigned, or restructured product,
• characteristics to be included,
• types of benchmarks, compliance, or branding,
• transference and storage of the data or product (depending on the medium),
• functionality,
• layering,
• maximum load,
• durability, etc.

There is an inordinate amount of questions and information that need to be addressed and gathered for Technical Specifications. Depending on the industry, different specifications will be gathered. For car manufacturers, data gathered may involve specifications for building engines. For pharmaceutical companies, specifications may involve the environment under which instruments or medicines will be manufactured. Meetings with subject matter experts and those involved will aid in gathering all relevant data.

Once all data has been collected, organize the information into a logical, readable format. When the document is completed, and appropriate parties (project managers, manufacturers, engineers, etc) have approved and validated it, the development team can now use the Technical Specifications to begin building a well-defined prototype.

As a note, Technical Specifications differ from Functional Specifications. Functional specifications are written for the manager/supervisor, describing how the product works based on the Requirements document. It does not contain any detailed technical data. For example, if the product is an application, the Functional Specifications will describe the flow of the program, how one section leads to another, the type of system/equipment needed, as well as error messages. In addition, Functional specifications are different from User Guides; although in some ways they are similar. The User Guide contains a set of instructions for the user to follow; how to use the product, what to do and not to do, and what to expect. No matter which type of document is written, remember to always write for your target audience.

More information on User /Operations /Training Documents will be described in the next post. If you have any questions, or feel I’ve left out information or wish more information on an item, please leave a comment.

What is going to happen after all meetings have been completed for a project proposal? How will it all be documented? One of the most important documents that a Technical Writer will create at the onset of a project is the Requirements document. It is basically an agreement which ensures that the client and the project managers are all on the same page. As a whole, it describes the project and outlines the client’s requirements and expectations. After participating in a wide range of meetings with all parties, and all essential information has been gathered, the Technical Writer will categorize the information and create a Requirements document. A Requirements document should contain:

• Date and authorization –lists dates, attendees, and decision makers.
• Description of the document – indicates the scope of the project. Include a brief description or explanation of the project, e.g., a new application or reporting process is being created, a pre-existing web site needs updating, or a customized version of an old application is needed. Make sure you include the client’s requirements and expectations. After this, note any additional partners or users that will be involved.
• Overview –describes the purpose and reason behind this project. Explain the circumstances that led to this new project. Provide a sentence or two on the business goals, funding, technology, or the intended audience of the new product.
• Proposal –indicates how the task will be accomplished. Include items, i.e., a migration will be involved, purchasing new equipment, or hiring consultants. Most importantly, specify time and expenses.
• Reason –validates the proposal. Note the benefits or advantages of this new product, application, or process. Why is this necessary? List all the pros and if any, the cons. If the case calls for it, outline previous features vs new beneficial features.
• Specifications –details the core requirements, e.g., equipment involved, database access, what has to be done-new tables, files, system enhancements, software needed, documentation, testing, etc. Include dates for priorities, milestones, and deadlines.
• Resources –indicates who will be involved- Developers, DBAs, Testers, Lead Project Manager, Sub-Contractors, etc. This will ensure you have the right amount of personnel to perform the job as well as the right people; else training will be required.
• Security –lists the types of maintenance and issues discussed and planned out, such as protocols, archives, contingency plans, etc.
• Diagrams and process flows –visually clarifies and reinforces the project and its systems or processes. Depending on the project, include an image of the completed product.
• Marketing –indicates when marketing comes into the picture and describes their marketing approach. Note any training or documentation (user’s guide, training manuals, advertising material) needed.
• Distribution –indicates what form of delivery is needed, e.g., what form of shipping is needed.

Outline and use sub-headings for each of the bullets above for further explanation. Once the document is completed, send it to the client and respective project managers for verification and approval. If the document is of considerable length, indicate what sections should be read by which party. Once all parties sign off and agree to the content, the Technical Writer can then begin to create the Technical Specifications of the product for the System Engineers, Developers, Manufacturers, etc.

The Technical Specifications document will be described in the next post. If you have any questions, or feel I’ve left out information or wish more information on an item, please leave a comment.