Author: Theresa Pojuner

One of the most essential components of a document is charts. As Technical Writers, we always write concisely, and clearly, but there will be times, when we need the assistance of charts to communicate what was written. Whether it’s for qualitative or quantitative explanations we sometimes need charts to truly present the whole picture. There are many types of charts.

• Graphic Charts are great at immediately presenting visual quantitative analyses at one glance. We use bar, pie, line, graph, spacial charts to show percentages, amounts of data, comparisons, changes in data, compositions, etc.
• Charts are effective for organizational charts by displaying the chain of command within a company. They are also known as hierarchical charts when we need to describe data structures.
• Pyramid shaped charts are used to show relevancy (most to least valuable assets), how one moves from top to bottom, or for showing relationships of how one element is connected to another.
• Gantt charts are used for scheduling project start and finish dates (managing project time lines), problem areas, different tasks, historical events and how one project might lead to another or intersect.
• Flow charts show how one occurrence leads to another. It clearly defines what occurs at various stages of an event. As an example, for any complex process, break it down into components. For each component, you can again simplify it further. When the images cannot fit on a sheet of paper or on one screen, you can use numbers or alphabets to point to another location to continue the diagram.

Charts are one the most common graphics. The type of chart you are going to use depends on what you need to define, explain or outline to the audience. Make sure it’s applicable, meaningful, and clear. Some graphic designs are more flexible than others. As a simple example, to show percentages, a pie chart would be appropriate, but you could also have used a scatter diagram with characters or figures instead to provide more interest. Scatter diagrams unlike the pie chart, can be used to also show a comparison over time using different colors for each entity. For this example, you could also have applied a line graph and blend colors using another graphic pattern to display overlaps. The best graphic image to use to get your explanation across to the audience is up to you.

To make it more appealing, think of how you would like to see the data and how the audience would like to see it.

• Sometimes adding pictures of items or subjects are helpful to make the chart or image more appealing.
• Use color, but not too much as it can cause confusion.

As a final note: There are a number of open source applications or tools which can be used to help you display your data. Make use of these tools and suggestions to clarify your document.

As a Technical Writer, we cannot forget about writing for the Call Center teams who have to answer to clients, buyers, or users of a product or application. They have to be patient, understanding, knowledgeable, and diplomatic. To assist them, the Technical Writer has to be able to create the materials needed by them. Training material, marketing material, analytical check lists, request forms all have to be created by the Technical Writer with the Call Center respondent’s profession in mind.

Call Center personnel need to be kept up-to-date on all products. To accomplish that, we can have training sessions, and to maintain communication, we can send out notification updates.

For notification updates, the following should be included:

• Version #, ISBN #, or any distinct code that distinguishes which product or application being affected,
• previous function vs. the new,
• new benefits, advantages, improvements,
• solution to problems, relevance, purpose, etc.

For training sessions, include:

• within the script the demonstration and explanation of all major components or facets that constitute the product or application.
• emphasis of what the product or application can or cannot do and especially what should not be done to prevent problems.
• a review of what is in the Appendix section to ensure that the glossary of terms and definitions are understood.

For the training packet:

• Include a diagram of the product or application.
• Create a highlighted features section that shows the products benefits and advantages, and especially what was requested from previous customers.
• Show a flowchart of the major stages of assembly of the product, or the major views of the application.
• Show an image of the major features of the product or the major elements of the application.
• Include a Resolution section containing a checklist of questions to ask in order to resolve the issue, e.g.,
  – How long have you had the product or application?
  – What steps led to the problem?
  Ask questions from as simple as ‘is the product plugged in’ to ‘what was the sequence of steps taken’.
• Create a section with diagrams depicting a bunch of frequent scenarios or questions and responses and use arrows pointing to the next question to ask depending on what the prior response was. For each scenario, you should end up with something similar to a hierarchy diagram. A hierarchy diagram is shaped like a pyramid or triangle where one point at the top leads to a wider base on the bottom. But instead of a solid form, you’ll be creating text boxes containing questions and responses and will depict how one response leads to another question or resolution.
• Include a section that lists all unresolved issues or problems that occurred during the testing phase of a product or application and indicate to whom the problem should be directed to or notified and create a response that will show the problem is known and is currently being corrected.

I think one of the most difficult jobs is being a Call Center respondent. If you have any more suggestions for the Call Center team, please leave a comment.

Gamification for this post is defined as applying a game, which also grants rewards, badges, or prizes. Can we apply this to technical writing? – Yes.

Gamification applied to an organization’s documents can encourage employees to:

• read their policies and procedures by providing a mechanism for them to check in and out in order to gather points which can then be redeemed within an organization’s store. The organization can provide rewards from something as simple as a better parking spot to gift cards.
• meet project milestones designated in requirements documents, technical specifications, or test plans during crunch time deadlines . The organization can reward them with, hopefully, some well-earned time off.
• participate in training programs and meetings. For this example, you could reward employees with, e.g., free lunches. Due to a lack of time, employees tend to skip training sessions and meetings. Gamification will provide an incentive for those with limited time to attend. Rewards can be given out for every individual, team, or Department who fulfill the requirements.

How does all this involve the Technical Writer?

As a Technical Writer, you could employ the use of Gamification in your, e.g., education or marketing material by being creative when designing these materials. The materials should be stylized and written in a game-like fashion, e.g., educational material should be written to cause the reader to want to read on. Not like a novel, but more in an educational way to make the reader want to learn more. Use your imagination and think of fun things to include.

Some ideas are:

• Include plenty of visuals for depicting examples or include case studies for reflecting what is being taught, mix in various tasks or quizzes, etc. Think of a puzzle and have the reader connect the dots or have a spreadsheet and have the reader fill in missing pieces.
• Include games, or questions and answers and challenges at the end of the learning program to make sure the objective was met and to reinforce the lesson. If the reinforcement quiz is electronic, then the points earned can be automatically added to the total rewards to earn more prizes.

Regarding marketing material and Gamification, an example is to apply QR codes and have the reader download an application from which they could learn more about the product.

What about the Content Manager?

As a Content Manager in charge of a group of Technical Writers, use Gamification to:

• provide incentives to encourage your team to meet milestones or deadlines. Challenge them to think of ways to improve current styles or to create new visual presentations to keep the reader more involved.
• help the team stay focused. When you are continuously writing and lose focus, you tend to get side tracked and sometimes the words seem to express boredom and that is one thing you do not want to do.

The Content Manager should harness team energy via games and challenges.

Gamification is a very popular way to gain more visibility and acknowledgment. If you have the imagination, then add more Gamification to your writing material.

I’ve come across certain words and terms that Technical Writers should be familiar with. The following are just a few outstanding key words that I felt were worth reviewing.

Compliance – is adherence or sticking to rules, policies, and procedures. This is very important for the Technical Writers as they need to be excruciatingly correct and precise when writing involves compliances (guidelines, policies, procedures, agreements, etc.) to avoid events such as errors, accidents, organizational catastrophes, etc. Compliance covers requirements for format and content; regulatory compliance, information governance, environmental compliance, compliance costs, coding, designs, etc. just to mention a few. Technical Writers compliant documents present what is expected.

Content (Document) Management– involves developing a content structure. It consists of creating, establishing, and distributing content and most importantly involves organizing content logically to make it easily accessible. It is also associated with knowledge management and information architecture which Technical Writers are involved in.

Cloud (computing) –allows you to upload, share, download and archive documents. The cloud is an offsite (remote) server or data center that people share and which provides a software service. It securely manages your documents (information or data) on a machine. It could also be known as SAAS (Software as a service), PAAS (Platform as a Service), etc., but that’s another topic.

Data (base, integration, set, value, management, metadata, mining, warehouse) – all involve the handling or management of data or information that is critical to a project or organization. How to manage ‘big data ‘is a growing concern for all organizations from small to large businesses as the volume of data keeps growing. Technical Writers help to interpret the information.

Gamification – is applying a game. Technical Writers now need to write about game-based applications which grant rewards to users, i.e., points, badges, bonuses, etc. Gamification is now becoming more and more a part of leaning, social media, and organizations.

Governance (of information, data) –is the controlling of or authority of information. It is a common term among businesses. Writing about the guidelines and policies needed to maintain the authority and regulation of information involve a great deal of work for Technical Writers who have to investigate and interview all the leads to create a structure that is understood and acceptable to the organization.

Hierarchy, Taxonomy, Information Architecture – are terms used to describe how a collection of information is organized (hierarchy), classified (taxonomy), or structured (information architecture). A Taxonomy is a form of Hierarchy and together they help to present the framework of an organizations Information Architecture.

Lifecycle – is the continuous work performed on applications, data, or products from the day they are developed to the day they are put into production or till they are no longer used. While working on a project, the Technical Writer is involved from the beginning starting from the presentation of an idea, to requirements gathering, to development, testing, and finally to the production phase.

Stakeholders – are the people involved in a project, i.e., graphic designers, web developers, business analysts, software engineers, clients, etc. Marketing stakeholders include designers, reviewers, and users. Stakeholders have an investment or interest in the project.

If you would like to see more like this, please leave a comment.

Why did I say that? ‘Oops’ what did I just do? What just happened? When doing a presentation, what do you do after an ‘oops’. You could have gotten too wordy and lost focus, or you went off script and are now lost, or you are experiencing technical problems, etc. So what do you now do? –Well for one thing, do not say,’umm’.

The following are a few tips that I have learned from my co-host Gail.

Be Adaptable – yup, you definitely have to be adaptable and easy going, and be quick, like Jack be nimble, Jack be quick, Jack jump over the candlestick. Be flexible to any change in your environment and work with it.

Be Brilliant – use your imagination and correct any problems you encounter; including your ‘oops’ statements or technical mishaps. How? Be prepared and have back up plans.

Be Courageous – have confidence in yourself that it’s ok that you fumbled or that something went wrong. Things happen, so just continue and don’t let the incident stop you.

Be Dynamic and say – ‘Wow that was a mistake!’ – This is the time to engage your audience or say, “Oops, well that’s embarrassing” and smile.

Be Energetic – show your energy and interact with your audience. Ask them if this ‘oops’ ever happened to them?—and what did they do? This will break the ice for a bit while you gather your thoughts and then continue on with your presentation.

Be Focused – on your next move, not on what just occurred. Take a breath and smile and continue and ask for assistance if need be.

Be Gracious – smile and say “Oops, I just made a mistake.’ There is nothing wrong in saying that. I feel this is an acceptable time to apologize.

Be Humorous – have a backup humorous slide as a backup for any ‘oops’ that might occur, or a story if there is a technical issue. This will occupy the audience while the problem is being worked on.

Be Yourself in an Introduction – during an introduction, if an ‘oops’ occurs, say something amusing, i.e. ‘ ‘So that must ruin my knowledge and reputation in this field…hehe’ and laugh.

Be Joyful – you love learning and teaching so show them the joy you have in presenting even after an ‘oops’.

Be strong and Kill the rise or drop in your voice because of the ‘oops’. Don’t let the audience know you’ve lost confidence. Instead, stay calm and say that there will be a short break if needed.

Be easy going and Laugh with your audience – they are the ones who want to communicate with you. Let them know you are just human and as such, will make mistakes. If you can, make a joke out of your mistake, or just say, ‘well that wasn’t correct, was it?’….and let it go.

Reword, restate, or rework your Message on what just occurred to make it right. Give the audience the right message you meant to convey to them.

And mostly, Never stop believing in yourself.

Why, because ‘oops’ happens to all of us.

Templates are extremely useful for saving time and providing consistency. They are short cuts to formatting and completing your document quickly and easily. They are short cuts because you no longer have to think about how the material should be set up or what style to use for particular types of documents. Having templates not only improve the appeal of the document by standardizing the look and feel of a document, but also by presenting data in a specific structure and hence preventing readers from wasting time by questioning why the configuration or format has changed again. Use templates for charts, lists, standard operating procedures, logos, etc. Templates can take on many shapes and sizes.

• Templates can be something similar to a form which you complete. It consists of predefined data, but may be missing certain specifics. For example, for IT, you can have particulars about a standard operating procedure or security, but have blank fields for application terms, names, or department labels. The Technical Writer merely has to insert the appropriate information into the fields to complete the form.

• Templates can be long and complex, especially in pharmaceutical and other industries where they have to comply with regulations. Employing the use of templates here is essential. The templates used in this area save the Technical Writer an enormous amount of time and effort when creating overviews, summaries, test plans, etc.

• Templates can be used within manufacturing industries, where documentation describes frequently used standardized hardware, material, operations, systems, or processes. A common example of repeated phrases or instructions can be easily recognized in your common package inserts, especially where safety issues are indicated.

• Templates can be used within applications or the IT industries, where processes, code functions, methodologies, procedures, etc., are reused. The existence of templates ensures accuracy and precision. The Technical Writer does not have to rewrite a methodology when it has already been written and verified. At most, the writer will either delete or add variants to a process or just merge the template in.

• Templates can be used in the HR departments for practices, procedures and most importantly, polices. Certain critical policies have to exist within certain HR documents and these can be simply inserted where necessary.

• Templates can be used when creating a glossary section. If one already exists, all relevant and essential definitions can be copied and embedded where needed.

• Templates can be used within the instructional domain for formalizing the look and feel of the manual as well as the question and exercise sections. These templates can have preset or default documented presentation approaches, styles, etc. that can be reused. The Q and A section can have templates for lists, images, notes, headers, footers, comments, etc.

Do not confuse a template with either a macro or a style guide. Templates are pre-made formats of information. Technical Writers should create their own templates and should not be underutilized. Templates should consist of reusable information, formats, and styles to simplify their work.

What do you think?

As a Technical Writer, you have no control over the number of revisions a document will go through when it comes to, for example, the Requirements document or the Technical and Functional Specifications. Even if you have attended every meeting to gather information for the new product, problems will arise. Why?

• Because more than likely, the product/application will in all probability have new requirements or changes at the beginning of the project and that will flow down to your initial writings. To avoid frustration, be flexible enough to go with the flow and update your documents as often as needed before the final approval of the documents are agreed upon.
• Because once the stakeholder or client sees a prototype, they might see things that they would like changed or added. When this occurs, be sure to document the fact and update all appropriate documents, i.e., the Requirements document, with authorization and dates. The Requirements document contains high-level material, along with critical client/stakeholder requirements. Be sure to make note of all the critical prerequisites at the front of the Requirements document as well as within any Technical and Functional Specifications. Note: ensure all critical information is also stated within the Test Plans to ensure validity.

A good Technical Writer has to be flexible enough to maintain the accuracy of documents by staying on top of all changes. Changes include and are not limited to updates to the application/product, SMEs (Subject Matter Experts), management, resources, timelines, etc. In other words, anything that has to do with the project.

A good Technical Writer will always take the initiative to perform some research to confirm that what was stated at the meeting could be executed. Make sure you know and are able to question the SMEs involved. Ask the SME if what was stated so far at the meeting is doable. Find out if there are any roadblocks or bottlenecks to the end result. Sometimes meetings are full of twists and turns and ideas get thrown around very quickly and certain issues could be lost. If you are not the recorder of the meeting, and are unclear of certain information, take it upon yourself to get all the facts and present them at the next meeting to ensure that everyone is aware of the requirements and are on the same page and have the same understanding.

If incorrect requirements exist, then the wrong resources may be selected, or the timeline might be incorrect, just to mention a few. Even though you do your best, there still might be changes down the road due to unforeseen circumstances, so be aware and be flexible to work with the modifications and adjust your documents accordingly. It is not easy to be a Technical Writer. Think of yourself under this situation as a mediator or intermediary – someone who is the liaison between two factions and who is trying to get the right information or to connect the dots to produce the right outcome.

The Technical Writer Project Manager (TW PM), has to be organized, analytical, detail-oriented, possess common sense and patience, and be an excellent communicator. The TW PM must plan, control, maintain, and be persistent in bringing the project to completion.

To plan each project, the TW PM will have to:

• analyze the project requirements,
• set milestones which indicate the critical dates,
• estimate the budget that is required to complete the project,
• identify the types of documents (as well as format) required for the project,
• select the appropriate resources (in source, outsource) to gather data, research, and create the content,
• ensure that the right tools are available, and
• determine whether or not the writers require training or need to be re-trained.

To control the all the projects, the TW PM has to:

• meet with all stakeholders to ensure that all requirements have been gathered,
• interview subject matter experts (SME’s) and developers to ensure understanding of the new projects,
• select appropriate team leaders to work on each project,
• maintain communication between the team leaders or members,
• maintain communication with all stakeholders to keep them informed of the projects status as well as to ensure that all required information has been gathered,
• ensure that each team stays focused and on target to ensure delivery dates are met,
• plan ahead and creates contingent plans for any unexpected delays and bottlenecks, and
• ensure that all problems are resolved.

To maintain management of the project, the TW PM has to:

• generate reports on the projects, budgets and overall status of the projects as well as reporting any unexpected issues,
• coordinate and manage the documentation (establish overall knowledge management processes and procedures which involve content taxonomies, styles, sharing, and distribution),
• interact with other departments for process improvements,
• perform final review/edit/proof reading prior to being published, and
• ensure establishment of style guides (definitions, metadata, processes, etc.) to ensure accuracy and consistency.

The TW as a PM has to focus on time, budget, and quality, as well as establish the high-level Project plan. One of the most important jobs of being a PM involves planning. Planning requires the PM to:

• plan out the projects (determine the work breakdown) and set milestones (critical dates, as to when the project has to be delivered),
• make sure that each team is informed of critical dates and ensure that team members will be available on specific dates, and
• establish backup plans for unforeseen developments or circumstances.

The TW PM has to also possess good judgment in selecting the right technical writers (or team leaders) for specific jobs. Once all of the necessary tasks have been prioritized, organized and under control, the project will be brought to fruition.

There are now many social media avenues by which technical writers could use to provide the information required by their target audience. We have FaceBook, Twitter, YouTube, Blogging, Pinterest to just to name a few. With all these social media mediums, do we still need to provide paper documentation or should we just answer questions from users via social media channels? Social media contains user generated content. Will readers be more apt to read documentation on electronic devices than on paper? We are so tied to our mobile devices, that maybe, we should just place all our documentation online. We have the Kindle, iPad, iPhone, Android, Nook, blogs, webinars, and podcasts, etc., just to name a few which can all communicate technical information electronically.

The target audience can gain access to all the information they need quickly and when they want no matter where they are. They can perform searches quickly for specific information and send comments and ask questions when they want no matter where the SME (Subject Matter Expert) is located. SME’s can be reached via links, e.g., tweets which can be added to the end of documents and get immediate responses; especially for critical questions and situations. All these new communication lines also keep all stakeholders abreast of critical situations, new knowledge, and keeps everyone up-do-date on all the latest events.

Even though this all sounds logical and exciting, should we do that? We still have to be aware of some drawbacks or problems. Not every type of information can be placed within social media channels, especially if it is related to confidential information. Confidential information is a huge entity. Each organization will have to decide which types of documents can be placed online for social media access, which to remain on paper format, and of course which to store/archive elsewhere. If the organization has an intranet or has been storing data within the cloud, they can set it up with privilege access only to retain confidentiality.

As a whole, using social media is useful for technical writers. Social media would provide easier accessibility to SMEs, users, upper management and those across all levels of the organization. One of the technical writers functions is to create help content and assist in creating marketing material. All these materials add to the good credibility of the organization and its products. Social media for technical writers in this area provides a plus for consumer service and sociability. If there is a problem w/a purchase or a question, the consumers can immediately, e.g., text, or tweet customer service quickly and the customer service personnel would be able to perform the search and provide answers quickly. In turn the customers/consumers, could, e.g., re-tweet about the organization, its support and cooperation, and might even reply with new suggestions or products for the company.

What do you think?

One of the most difficult things to do is to describe to someone how to put something together or how to operate a device. How do you communicate to someone the procedure to put parts together to build a plane, boat, or car? Or how do you put the pieces of a table or chair together? For objects such as Lego pieces, images are constantly used rather than text as that seems to be the easiest way to communicate to the target audience (mainly children – but I do like them as well). So why don’t we always use pictures? We can label each item numerically or alphabetically and just say to insert A1 to B1 and B1 to C1 and work our way to the end of the alphabet and then begin again with A2 to B2 and B2 to C2. Everything remains in sequence. But what if you needed to turn B2 at an angle to fit into A2 or how do you indicate the procedure to screw or hammer the bolt or nail A1 to B1? Can a picture show that? Using only images can work in certain cases, but for other situations, it would be more advantageous or easier to communicate the instructions via images and text. Images (drawings, cartoons, stick figures, etc) alone, can convey certain instructions but you need to be constantly imaginative. If you are not, the easiest way would be to describe the procedure and apply an image.

Look at a toaster manual. I cannot think of one appliance that we have purchased that does not have a manual minus text and images, such as, the toaster manual. Notice that even before we are told how to operate the toaster, or how to plug the toaster into an outlet, we are given warnings with what not to do. All critical information is always towards the front after the introduction section. The technical writer realized that there was a danger involved in using the appliance and decided to place the warnings up front. Notice that the warnings are not just plain text. They have a special warning icon as well as being denoted in a different font. How can the warning have been displayed via images alone? The next section within the manual (following the precautions) contains diagrams of all the mechanical parts that the consumer needs to be aware of for the operation of the toaster. Again, text and images are used.

I know I chose a simple devise, to develop a question or a point, but what if we were describing the use of a more complicated piece of equipment? And what if we were to distribute this device globally? How would we be able to illustrate how to operate it?

As technical writers we always have to remember to communicate the essentials in a simple and appealing format. So I think in most cases, you need both images and text, but yes there are cases where only images do work. What do you think?