Author: Theresa Pojuner

How do you create your training manual? We have all used training manuals. Some to our dismay and some we wish to keep and refer back to. What makes a good training manual is the relevant information that is supplied and how it is presented. The Technical Writers/Communicators will be the individuals assigned to create this reference as they are the knowledge holders or subject experts. To begin:

Determine Your Audience

What do they need to know? What tasks are relevant to them? Some learners do not need to know every detail of a product. What are the main objectives of the manual and the training? For example, if it’s for:

• Marketing or sales, – explain how the product works if it is new or how it now works if it has been revamped. Emphasize the selling points, ease of use, cost, quality, etc.
• Customer service personnel – provide more detail in its functionality and relate prior issues and what questions to ask and whom to contact.
• Developers – provide more technical detail and specialized units or modules.
• Users of technical programs – focus on functionality and exercises.

Those are just a few of the many different types of training manuals that are written.

Determine The Design

How the manual is designed will be determined by what you are training the audience for. In deciding on the look of the manual, tables and visuals are always suggested as they present a clearer picture of the product and what it does. Tables also present a clean definition for each relevant item. It is also suggested to use two column formatting only in special cases to break up a flow for interest. Following the above examples, if it’s for:

• Marketing or sales – use images followed by descriptions and apply bullets for ease of readability.
• Customer service personnel – provide images followed by additional detail in table formats to explain functionality and issues and resolutions.
• Developers – provide plenty of images, flowcharts, and tables for data locations and settings.
• Users of technical programs – include screenshots with pointers and tables for steps, explanations, and definitions.

Customizing the look and feel of a training manual will make it easier for the learner to follow.

Determine The Content

Content centers on the target audience. For example: if it’s for

• Marketing or sales – include sections compiled of background and purpose, how it was designed, the demonstration process, a complete view of the product with pointers indicating relevant parts of the item, a reference sheet (quick guide), etc.
• Customer service personnel – include sections compiled of functionality, descriptions, definitions, appendix, previous problems and solutions, reference sheets, etc.
• Developers – include sections compiled of objective, requirements, specifications, data, functionality, programs, software, diagrams of how it should look, mappings, etc.
• Users of technical programs – include sections compiled of the business process, ‘How to…’ perform a task, relevant images (figures, tables, screenshots), exercises, glossary, etc.

Ensuring the content is written well and pertinent to learners will instill within them confidence to perform a good job.

Add in suggestions from a previous post, ‘Tips To Get Your Document Read’ to produce an instructive and useful training manual.

Please leave a comment if you have other tips when creating a training manual.

How do you handle change? Changes are not predictable. What happens when changes occur on a project and you have just been notified at the last minute that documents have to be revised, revamped, and need to be transformed to have a different format?

Panic sets in. What happened to the change request process? Why weren’t you notified that changes might be coming? This scenario can occur:

• when a project manager and\or a client demands changes at the last minute,
• when updates and requirements were misinterpreted, or
• when other changes occur such as when product parts have suddenly been discontinued.

This can easily happen within an organization or global organization’s environment.

Project Plan

To ensure that the proper documents will be written, updated, or revamped, give yourself plenty of extra time within your initial project plan. If stakeholders do not agree to the expanded time frame, explain to them about the what-ifs. What

• if the client demands a change,
• if the budget was estimated incorrectly and a resource has to be eliminated, or
• if the whole scope has to change because of unforeseen circumstances.

Your schedule has to account for these situations.

Staffing

If there is a history of late changes within projects, assign backup technical writers, and just to be on the safe side, assign more than one to assist in emergencies. Make sure each writer is well versed and acquainted with the particular project topic and more importantly, that the writers also work well together. Staffing conflicts are not needed in situations where tight deadlines have to be made.

Back Up

Take a step back, especially if you are the only technical writer. You can ask what happened to being kept in the loop of change requests, but no matter what the reason behind this new agenda, you now have to move on and make all the revisions and create new documents, formats, and/or images to get the project completed on schedule.

• Get a complete list of prioritized changes.
• Then find out what format updates are required. Do it in that order. This way, at least you know what revisions have to be written, what text and data have to be replaced or amended.
• Simultaneously, focus on having the correct images redone or replaced. Formatting can be the final step.

Getting The New Data

Revisit your subject matter experts, developers, stakeholders, etc. to ensure that all the new information you have been given is correct and accurate. If they also have to adjust their plans as well, make sure that they keep you in the loop and provide you with all the information you need as the project moves on.

Post Morten

Here is where you discuss the ups and downs of the project. What went well and what went wrong and how to make it better the next time around. Do not dismiss these end of project meetings. They are relevant and help in making the next project run more smoothly.

A quality document has to communicate effectively to the target audience. If quality documents are to be produced, allow for flux and flexibility within every project.

How have you been able to handle sudden changes? Please leave a comment and share your experiences with us.

Question – Is reviewing your document clear and concise? – How do you know? Has it been written for your target audience? Most importantly, is all the information correct? We can write and write, but when do we stop and how much is enough? Here are some checks to ensure that you’ve written and checked all aspects of the document you’re delivering so that it is ready for your audience.

Plan it out

For specific documents, make sure that the most important items have been included. Prepare a list of must haves for each document you are preparing. Here are some simple examples:

• • For requirements documents, did you insert the project scope and essential items outlined and prioritized?
  • For user guides, did you review each step, provide enough images,, and did it meet stakeholder’s needs?
  • For specifications, did you provide all necessary data and figures/images and ensure that all pointers refer to the correct items?
  • For test plans, did you include location of objects and every scenario to be tested?
  • For marketing, was there enough data and information for sales engagement and revenue generation?
  • For RFPs did you include all the correct figures and terms?

From your research, you will know what has to be included in your work. Use the examples above and customize and create your own personal list of checks for each document Once each item on your list has been checked off and validated, then move on to the next steps below for reviewing the document further.

Check for Clarity

Make sure that you have included every description and explanation that is necessary. Did you use your simplest words to be as precise as possible without ambiguity? That is, make sure you have included all the right steps and diagrams and that all instructions, explanations, and relationships are in the right order thereby validating your content. Double check and make sure you have an answer for every possible question.

Check the Flow of Words

Once you have included all the key factors in your document, you have to make sure that it is readable. Take a break and then read the material as if it’s the first time you are reading and seeing it. Make sure there’s a natural flow or rhythm in the words as you read. Reading as if you are speaking is a good indication of whether or not the sentences are readable and clear.

Do Your Editing

• For spelling, the best method I use for checking is to read the text backwards.
• For grammar, check sentence structures.
• For repeating words, use your thesaurus to use another phrase

End Goal

We’ve all faced similar problems where we can’t get answers to questions we have for a project. What do we do when it comes to road blocks? One solution is to gather your knowledge base and hold a meeting and communicate to all project members and stakeholders that you have hit a wall. But prior to the meeting, be sure to create a plan and email an agenda.

Communicating In A Meeting

Break up the meeting by agendas, groups or one-on-one, level of expertise, or departments. Present the reason for the meeting and define the problem. Let them know your concerns, status, and what information you need from them. Let them know that the project will be in jeopardy or that deliverables will be late. Present a list and let them know what you have and what is missing. Review the list and see if they can assist in any way or give you some leads. Just as you would deliver your documentation in a presentable manner, do the same for your plan. Simultaneously, find out why you cannot get the information or the help that you need. Maybe your associates are overloaded as well. Find out their issues and concerns and see if you can assist them in some way. Teamwork plus collaboration always equals a positive outcome.

Asking Questions

These gatherings are your key to finding answers. Ask all the questions you can as part of your plan. You could make a list of assumptions and ask people if your assumptions are correct. For example, describe what a process does or what job someone performs and see if they agree and follow through on the subject with more questions. Once people begin to talk, they’ll keep talking and it is a painless way to get information. It is, however, dependent on the individual. Some personalities will need coaxing, and others might give too much information. Sometimes you get direct answers and sometimes you go in circles, i.e., when trying to find the exact solution to a trouble-shooting issue. For cases like these where you have no control over getting a reply, just put it aside, and make note of it. But be persistent and return to the subject when there’s a possibility for an answer.

External Help

Sometimes you need to go outside the group to find some answers and in so doing, be able to ask the right questions. The more you know, the better questions you can ask. There is nothing wrong with finding some outside help to get to the root of a problem.

Respect

Just as you need to respect the knowledge holders, they need to respect you In other words, you have to not only know the audience you write for, or answer to, but you also need to know the audience you are gathering information from. Is what they’re working on impacting your priority? Can you help them so that they can help you? Find out at these meetings, what the issues are and work with them on analyzing and resolving them. As always, two heads are better than one.

If you have had similar experiences and other solutions, please leave a comment.

There are many answers to the question on how and where to place text for images, figures, snapshots, etc. Should text be embedded or placed below, beside, above, or to the left or right of the image. It depends. For simplicity, let’s use the word ‘diagram’ to represent images, figures, snapshots, pictures, charts, etc., in our examples below.

Embedded text box

If the diagram is used to show where the keys (buttons, knobs, switches, controls pins, screws, levers, etc.) are located, use text boxes with arrows pointing to their location.

Large diagram

If the diagram is large, crop it just enough to focus on a particular element. If the diagram is too large, and the text that follows falls on the next page, either shrink the diagram or decrease the font size of the text. Try to keep the diagram and the text together.

Small diagram

If the diagram is small, placing a text box with explanations to the left of the diagram allows for ease of readability. This also leaves room for the reader to scribble in extra notes to the right of the diagram (if they wish).

Using a table

For explanations of crucial mechanisms, create a table below the diagram, and list the names of the instruments or devices in one column and the explanation or usage of it in the adjacent column. If additional diagrams are needed, crop and embed them to fit into the table cells.

Instructional text

When giving steps to perform a function, use the table format and place it below the diagram. Number the steps in the table, followed by a heading, such as ‘To initiate…..’ followed by sub steps (if needed). This is an easy format for readers to follow and they can also easily see what tasks need to be accomplished. As above, if one of the steps require another diagram, shrink or crop it and embed it into the table with the explanation to the left of the image (again for ease of readability).

Text Placement

I tend to always put the text below a diagram. We read from left to right and downward, so it is natural and easier for the eye to move down to read text after a diagram rather than up. Also, the image of the diagram is still fresh in your mind as you read down. The only time I have used text above a figure is when explaining, e.g., a graphic or chart or anything that involves numbers. For example, if the preceding text of a diagram is similar to any of the following statements: ’In the following xxx. .’, ‘For example…’, ‘Note the following…’, then I would place the diagram after the statement.

Are Technical Communicators/Writers more right-brain or left-brain thinkers? In a previous post about a technical writers soft skills (https://staging.management.org/blogs/communications/2013/03/05/soft-skills-of-a-technical-writer/) , I defined the soft skills of technical writers as being made up of communication, emotion, concentration, and common sense. …...’ It is being able to see and interpret the whole picture and to translate it into useable and understandable terms for others ....Technical Writers use their soft skills to…communicate,…listen,…understand,….lead….’

While writing the above, this question came about: ‘Are Technical Writers more right-brain than left-brain oriented? If we define the difference between right- and left-brain thinkers as…..the right side of the brain controlling the art, music, humanities side of your thinking, and the left side featuring the logical, analytical side., you can associate the right side of the brain to artists, musicians, teachers, designers, or philosophers, etc. while the left-side dominant thinkers tend to be analysts, statisticians, scientists, or problem solvers, etc.

The right side of the brain helps us with:

• Understanding the audience
• Understanding what is needed by clients
• Communicating and collaborating
• Listening to others
• Designing good content
• Being able to work well with others
• Developing creative ideas
• Training abilities
• Writing well
• Handling stress
• Leading

The left side of the brain helps us with:

• Being technologically oriented
• Seeing and understanding the technical and scientific aspects of a product and functionality
• Building a logical workflow of a system
• Analyzing data
• Supporting quality and accuracy via trouble shooting problems
• Usability and regression testing
• Understanding System enhancements
• Strategizing the detailed organization of a document
• Making decisions
• Recognizing and sticking to timelines
• Setting priorities

I think Technical Communicators/Writers are both right- and left-brain oriented and combined they bring out their best attributes.

Other questions arose, i.e., where does user experience of an application fall for the Technical Communicator/Writer when they function as a user interface designer? Is this a more right- or left-brain oriented skill? Is the ease of use of an application or what is presented related to one side of the brain? Maybe it’s the right side as it involves the user interface design. But then, argumentatively, the functionality and logistics is left-brain oriented. I think the same goes for proof reading or copy editing. Both sides are needed for checking content.

When you look at the whole picture, that is, the definition of a Technical Communicator/Writer, it doesn’t seem like one side is more dominant. We see that having both sides of the brain are needed to relate information. If you go too far to the left, the writing can be too intense, boring, or mind-numbing and if you go too far to the right, the content might not be serious or be too varied or diverse and be confusing because it doesn’t hit the nail on the head.

To be a good Technical Communicator /Writer, we need the right and left side of the brain to accompaniment each other; to balance each other out.

If you think otherwise, please leave a comment.

If you are a beginning Technical Writer or an experienced Technical Writer, how do you, respectively, display your skills and find your first job or find more jobs in technical writing? Here are some tips:

For beginners, write about your job – begin writing in your current job about all that you know, and make sure that it is on your resume. Write about your daily activities, or any instructions you’ve been given to perform a task. Record or document your knowledge. When review time comes up, make sure that your supervisor or manager knows what you’ve documented. You never know, maybe a new technical writing position will occur and you may be approached for it. Note: this also displays your detail documentation skills.

As another example, you may have been assigned some detailed task that involves, e.g., ensuring that a document or product is tracked. For this task, or some similar task, you may determine you need to create a flowchart or a tracking module or check off list with adjacent initial boxes to certify nothing is lost in transit. List names, places, an event time table, accessories needed (how much and from whom), location, etc. Use your imagination and create some icons to indicate readers, edits, final edits, products, etc. Create a folder and document all this data so that you will have it ready for the next time you need it. Also note all unexpected incidents, such as delays, interruptions, and postponements. This way you will be prepared and know how to handle these problems the next time around. Note: this displays your organizational, research, interviewing, interpersonal, and analytical skills.

For beginners and experienced writers, create a blog to showcase your work, ideas, workshops, training, etc. There are many free packages on the web to use; just Google ’open source blog software’ to get a listing.

If you extensively use a particular manual, application, or package, write about your favorite features of, e.g., a word processing or spreadsheet package and explain how to use it step-by-step to perform a particular function like generating a report. Just remember to be clear, concise, and error free when explaining which steps to take to perform the specific task(s). Create a flow chart to depict the steps or create a diagram using another package and save it into your blog. Detail how and what package you used and include benefits, ease of use, etc. Or, you can just hand draw a picture to show what you mean. When others read how you explain steps, procedures or processes in your blog, they will see how professional you are.

As an added note, see if you can guest blog, create a training manual or e book, teach at a local school or organization, join and participate within organizations, contract freelance work, tweet about your work, perform volunteer work, interview people, market and brand yourself, and definitely network.

Following through with any of the above suggestions can show off your technical writing skills.

Good Luck and please leave a comment about all your strategies to get into being a technical writer (technical communicator, technical editor, technical illustrator, technical trainer, technical translator, etc.). For more information, go to Steps To Become a Technical Writer (https://staging.management.org/blogs/communications/2012/04/01/steps-to-become-a-technical-writer/) or see my e book on Smashwords (https://www.smashwords.com/books/view/213398).

What are soft skills? They are made up of, for example, communication, emotion, concentration, and common sense. Technical Writers need these skills to get the job done. A Technical Writer today has to possess some technical knowledge, which is equivalent to having hard skills. But the hard skills can’t be accomplished without having some organic soft skills. These right-brain traits are important for Technical Writers. It is being able to see and interpret the whole picture and to translate it into useable and understandable terms for others and that is where soft skills come into the picture.

Why Soft Skills

Technical Writers use their soft skills to gather the information they need to write a clear, detailed, and understandable document. Soft skills are needed to, for example:

• communicate with all levels of an organization,
• ask questions and more importantly, listen,
• understand people as well as the mechanics or processes of a task,
• lead a group of Technical Writers to produce written information,
• verify and confirm facts.

Emotion

Technical Writers have a passion and an appetite for sharing knowledge and communicating. They have a sense of curiosity and are also respectful of the individuals they are interviewing; the stakeholders, the owners of a written document, as well as their audience. Respecting the culture of an organization allows them to understand the attitude and behavior of their audience and consequently gather relevant knowledge. Technical Writers are very people-oriented and use this soft skill to see what moves and inspires individuals to accomplish goals and to see and understand what is needed by them. Technical Writers are good listeners and empathize with the users, team players, stakeholders, etc.

Concentration

Technical Writers focus, consolidate, and organize their train of thoughts. They use their sense of concentration to categorize and arrange all their gathered material to execute a good presentation. They also use this ability to see what is required and appreciated by their audience as well as to be able to prioritize their work. In addition, they use this ability to focus on the scope, tone, and quality of a document, as well as its goals, deadlines, and weaknesses.

Common Sense

Technical Writers bring forth their experiences and use their common sense to work with others; to be supportive, honest, open, and to be aware of simply what is good and what is not. They use their common sense to know, for example, what is critical and confidential information. In addition, they use their good judgment and practicality to detect or sense possible conflicts and be able to deliberate them.

From the above, we see then that Technical Writers make use of a lot of different soft skills in order to communicate verbally and via text. They need to be able to speak clearly and to write concisely and to be error free in both categories. Technical Writers can be very technically versed, learned, and be familiar with the most up-to-date technology, but without soft skills, they will have a difficult job.

How do you measure whether or not a document is communicating what it should? How do you define good documentation? – I define it as being applicable, usable, and error free. Documentation has to be written for the target audience as everyone has different roles and responsibilities. The following questions can be asked via feedback or during review time to ensure that all written material accomplishes its goal.

Feedback

Feedback can be gotten through comments, check points, or star ratings. Preprinted questions can sent out electronically or be attached to the back of each document. Some questions to ask are:

• Did you read it in detail
  • If no, what did you skip
• Were the Table of Contents, Appendix, and examples helpful?
• Was it easy to read and comprehend?
• Was the flow of the document consistent?
• Was the layout of the document suitable for reading?
• Were the activities suitable and helpful?
• How long did you spend on each portion of the document?
• Was it complete and understandable?
• Was the time spent worth it?
• Were you able to use the documents and did not make any mistakes while applying the knowledge?
• Would you refer this document to others – recommendations?
• Would you like to add something to the document?
• How often should this document be reviewed?
• Who is using this and where?
• What was missing-what else should be captured?
• Were you able to learn from this?
• Should there be more breaks or white space?
• Was the format of the document suitable?

Depending on the type of document written, focus the questions on the audience reading it. For example:

For trainers, coaches, mentors, instructors ask:

• Were there enough exercises, separations, directories, and appendixes?
• Did it contain accurate and precise content?
• Did it help to prepare the staff and/or learners?
• Did it reinforce learned knowledge

For a global organization, ask:

• Did the document capture and relay the objective of the organization?
• Was the correct knowledge transferred?
• Was the language used suitable, appropriate and understandable?
• Was the usage of the document easier than meeting face-to-face?
• Was the translation software able to phrase local terminology suitably?

For an IT department or technical personnel, examine the following:

• For Project managers, developers, and stakeholders,ask:
  • Were the requirements, and specifications complete enough?
  • Were there enough designs, illustrations, samples or were there too many?
  • Did it provide the appropriate critical security information?
  • Were the designs, cases, and purpose of the document accurate and reliable?
  • Was it organized well?
  • Were there enough business cases?
  • Was there enough data and information for marketing for sales engagement?
• For the QA department ask:
  • Were there enough scenarios to aid the testers?
  • Were documented requirements and specifications met?
  • Was there enough data for testing?
  • Was enough information given to access data and equipment for testing?

After collecting all the feedback, keep a running chart of the responses- keeping track over time will show you the worthiness of a document.

If you have had experience with measuring the quality of a document please leave a comment.

Wireframes allow developers, designers, trainers, managers, marketers, etc. to communicate and transfer knowledge to different types of audiences through the use of diagrams, images, models illustrations, or drawings. They exist in the form of screen shot, diagramming, and modeling applications. A few of these features are already included within existing applications. These suites of tools provide the ability to translate concepts into functional requirements, prototypes, and eventually real models or products. Another important capability is the facility to present easily understandable views of processes and procedures.

They are extremely useful in helping to avoid misinterpretations of deliverables in a global market by providing:

• a view of, e.g., user interfaces, procedures, and schemas (for interactions, work flows, and relationships),
• the ability for early design decision making , and
• a means for translating complex ideas into simpler concepts or thoughts .

Many of these tools are accessible on the web for free. Here are some tips for choosing a wireframe:

• Make sure that the application does what you need it to do and functions in a way that is easiest for you to use. For example, can it easily help to develop use cases, testing scenarios, flow diagrams, site maps, functional specifications, charts, processes, prototypes, etc.?
• Can it create a view of the information architecture and aid in organizing data into categories, visual frameworks, and models?
• Does it fit within your system platforms (web-based or desk-top application)?
• Can saves be performed in various formats and are they shareable?
• Check out the options. Is it suitable for you – can it help with online static content as well as dynamic content?
• Check out ease of use. Does it provide, e.g., ease of navigation, drag and drop, preformatted styles and templates for flow charts, org charts, and diagrams.
• Is it interactive; can it create a simulation or can comments be added? Does it allow for online learning, presentations, storyboards, and mockups to explore a wide variety of design options using different formats?
• Are objects reusable?
• Is it flexible enough for use on mobile devices?
• The most expensive may not be the best application. Check out licensing agreements and costs before purchasing. Make sure you have the correct number of licenses for the number of machines or platforms that is needed for the present and the future.

In the end, when deciding on a wireframe tool, think of the above questions as well as:

• Can it help to provide information and knowledge to help meet business goals?
• Can it aid in training and marketing for understanding the product?
• Can it help in presenting departmental, software, or functional processes?
• Can it help to meet the company goals and provide the desired outcome?

Wireframes aid the technical writer in creating a structured framework for communication. It is the skeleton of a product or process and is a great aid to get technical writers through the first stages of development. You might say it’s an outline and provides a background from which to begin building.

Please leave a comment if you have used or find that wireframes are indeed useful.