Category: Advertising & PR

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.

Isn’t humor great? Doesn’t it feel good to laugh? And aren’t presentations with a little humor mixed in a lot of fun?

Of course, humor is great when it works, but what happens when you try to add a little humor in your presentations, and it just doesn’t fly? Not so fun, not so good.
Not too long ago I was working with a small group on their presentation skills, and we began talking about humor in presentations. The client quickly pulled me aside and said “Gail, we don’t encourage humor in our presentations around here. We find it way too risky.”

It got me thinking. If humor is so great when it works, and so bad when it doesn’t, maybe we need to learn a bit more about humor so we can decide when and how to use it, and how much of a risk we want to take.
Today let’s focus on why you might want to use humor. In future posts I will discuss the when and the how of using humor in your presentations, and finally, what not to do in using humor. My hope is that you might make wise choices in trying a little humor when appropriate in your presentations.

So why should you consider the use of humor, despite the risks?

• Humor can relax the audience – and us. One of the outcomes of laughter is a sense of release. If you are feeling stressed, or your audience is worried or distracted, good humor can be cathartic to everyone.

• Humor can build bridges. Once we have laughed together, we feel more like friends. We broke the ice. We are on the same side. Once we have laughed together, the audience is vested in your success, and you may feel and respond to that support.

• Humor can make us stand out from the crowd. When we spend all day in meetings and listening to webinars and speakers, one who makes you laugh feels like magic. Laughter releases endorphins, and who doesn’t need that in the midst of the workday.

• Humor can create and maintain interest. If you are a speaker who occasionally injects some humor, I am going to stay tuned in so I don’t miss the next one. I actually listen to you with anticipation.

• Humor can make us better speakers. When we see the smiling faces of our audience, and feel the release that laughter brings, and the feel-good chemicals start coursing through our bodies, we can feel more comfortable and confident. We think faster, speak with more authority, and stay in the present moment. No more worry, fear, or trying to remember our lines; we just communicate.

It’s all good. If the humor helps the audience relax and relate to us, and brings us closer together, then all is well and using humor was a wise choice. Of course, when it all goes badly, we get a different outcome. More on that next time.

How do you use humor in presentations? Is it OK to use humor in your culture? Has it ever backfired on you? What kinds of humor seem to work best? What advice would you give new or inexperienced presenters?

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.

Skilled presenters have a sense of ease about them. You see it on their faces, in their gestures and body language, and hear it in their voices. Here is a list of the most important delivery skills to master.

1. Stand tall from the ribcage; this looks confident–strong yet relaxed. Keep your head straight but not rigid. Plant your feet. Bravo!

2. It is best to plant your feet in place most of the time. When you move, move from point A to point B deliberately, then stop and plant your feet again. No pacing.

3. To work the room, stand in the center for your opening, move every 2-3 minutes or at the start of each new topic, then return to center for a strong close.

4. Keep your hands in a neutral, relaxed position at your sides or at your waist. If your hands are locked you won’t be able to gesture.

5. Let yourself gesture naturally, and then let your hands go back to neutral/resting position.

6. For better voice projection get into the habit of opening your mouth a little wider. This helps with both volume and enunciation.

7. Sound like an expert. If any of your phrases sound like questions, you will undermine your credibility. Firm downward inflections sound best.

8. The eyes have it: to appear confident, practice making smooth, steady eye contact.

9. Pause appropriately; before you begin, after you make a point, between slides. Don’t rush.

10. Face it; your face is showing. First make sure it is relaxed and neutral. No frowns, no tension, no licking your lips. Check a mirror.

The best way to improve your delivery skills is to video a presentation or rehearsal, then watch it back with a trusted colleague or coach. Be sure to look for your strengths as well as those things you would like to change. Little changes in delivery skills can make a huge impact, but work on just one or two areas of improvement at a time.

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.

Ever hear the phrase; you can’t NOT communicate? I think it’s true, because even when you aren’t speaking, your body language is.

Effective communicators pay attention to what their body language is saying. Why? If there is dissimilarity between what you are saying and how you are saying it, your message may be misunderstood.

Let’s say you have agreed to take on a stretch assignment at work, and you want to assure your boss that you are good to go. But your arms are folded over your chest, your head is tipped down slightly, and your words are soft and flat as you say, “I can handle it.” Does your body language agree with your words? Not in this case, and when there is dissonance listeners tend to believe the nonverbal. So your boss may hear, “I’m not sure I can handle it.”

Let’s take another example; a member of your team has just asked for some of your time to discuss an issue. You are pressed for time, but agree to have the conversation anyway. As you listen, you inadvertently keep glancing at your watch. What are you signaling about your time and attention?

In order to minimize the risk of sending nonverbal messages that negate or discount your words, begin to practice these habits:

1. Become aware of your body language. Is your head tipped down? Are your arms folded over your chest? Are you fidgeting? Are you looking away from the person? Does your face suggest stress? Just begin to notice. (If you find this difficult, you might be able to increase your own awareness by noticing the body language of people around you. Are they bored? Angry? On top of the world? How can you tell?)

2. Build neutral habits. If you habitually spin your pen around in your hand or tap the table, train yourself to be more still. If you bounce on your feet when speaking, or cross your ankles, train yourself to stand still in a balanced position. If you tend to show anxiety or stress on your face (raised eyebrows, tight mouth) train yourself to relax your face. Breathe to still your energy.

3. Look for alignment between what you say and how you say it. If you are expressing thanks or positive thoughts, try for a smile in your eyes and a sparkle in your voice. If you are expressing a serious topic, look for firm, assertive body language. If your message is neutral, so should your body language be.

4. Get some feedback. Ask a colleague or trusted advisor to observe you in a number of situations. How well-matched are your verbals and non-verbals? If they notice any habits or concerns, try video recording some of your conversations to pick up on these discrepancies. If you notice a lot of misunderstandings and think you might have a problem, ask a skilled coach for guidance.

When your body language and message are synchronized, you will experience fewer misunderstandings, and your messages will come across with more power and more impact.

Communicating on the Internet is equivalent to having a face-to-face conversation with someone, except that your dialogue takes place over a network. Emailing, chatting, texting, tweeting, etc., has become a popular form of communication. You can have a conversation with anyone from anywhere and get up-to-date information on what is happening when and where at an instant. This is great, but as with any good thing, you still have to be careful.

Basic practices you should be acquainted with:

• Be attentive of what you write on posts or comments, as everyone will see it. Be respectful and follow the ‘Do Not’ rules mentioned in the previous post on Netiquette.
• Be aware that what is written might be archived or replicated. Deleting or sending an email or chat to trash does not wipe it out completely. So be careful of what you write.
• Be cautious of whom you email/chat with. Make sure you know and trust the individual you are communicating with.
• Be wary and guard yourself against any unwanted email, web sites, or links that you are not familiar with and that do not seem legitimate. This may lead to viruses, bugs, or hidden programs that could corrupt and destroy your system.
• Be careful of your spelling of words as a misspelling can cause a huge misunderstanding. You do not want to be known as the individual who recorded Mr. Mary Jones when you meant Mrs. Mary Jones.
• Be conservative when using acronyms. There are an infinite number of acronyms and there are an abundance of similar acronyms having different meanings. If an abbreviation is used, spell out what it represents before continuously using it as the reader might not be familiar with it. Also, limit its usage.
• Be concise when emailing. In general, enter the purpose of the email in the subject line using as few words as possible to explain the content of the email. Within a business environment, if the content of the email is lengthy, include it as an attachment.
• Be sure you read your correspondence carefully. Make sure you read and understand what is in the email-do not assume. Else, you might reply incorrectly to the email and a host of miscommunications can occur. Likewise, be diligent and reread what you’ve written to ensure that what you’ve written will be understood.
• Be sensitive of the tone you use while writing as the reader cannot see your visual expression and cannot distinguish sarcasm nor annoyance from pure statements; be cordial.
• Be aware that management likes point-by-point information in an email, like a telegram, whereas you can write more informally to a co-worker.

In essence, when writing, chatting, or posting on the Internet, make believe you are conversing face-to-face with that person or group. Be polite and be sensitive to them. As the old saying goes, ‘Put yourself in their shoes’. Or, as the new saying (The Platinum Rule) goes, ‘Treat others the way they would like to be treated’.

We all know we probably could do a better job of listening. But have we really thought about what benefits could accrue to us and our relationships when we really listen? Listen to Doreen Johnson, founder of River Dreams™, a coaching business that helps people express their true nature. In an early corporate position, Doreen noticed herself checking her watch as meetings dragged on and on, and there was lots of talking but much less listening. She made a conscious decision to remove her watch and focus on really listening to what people were saying. She listened to the whole person, trying to determine the whole message, not just the words. Over time, she noticed her meetings were becoming less contentious, more productive, and shorter. People noticed that meetings were so much better, but they didn’t really understand what had changed. So started my conversation with Doreen, and after this story, I hung onto her every word.

True listening is not a set of skills as much as it is a state of mind. If you listen habitually, you will react to what others say. You will cut them off if they tend to go on and on. You will argue with them if they don’t agree with you. You will tune them out if you know where they are going because you have heard it all before. The result of this kind of listening is patterned behaviors which are repeated endlessly and often at length. I picture each of us enclosed in our private capsules, bumping into one another like so many bumper cars, each talking to hear ourselves. Noisy and funny sometimes, but also repetitive and somewhat meaningless. (Kind of like our meetings, only without the humor?)

Now what happens when you apply a number of listening skill rules? You know the ones; make good eye contact, nod, and say “uh huh” a lot. You can do all this and yet not really be listening. Now we are in our capsules, knocking into each other, and pretending to listen. Maybe we are listening to the words, but we still aren’t connecting at more than a superficial level. Applying technique and rules really doesn’t do much until we are ready to make the radical leap to true listening.

When you make a clear, conscious choice to simply listen without judgment, but listen to fully understand, you are listening with your heart as well as your head and your ears. You automatically take in the whole of the communication; what is being said and what is not. What the nonverbals are telling you. The tone of voice. The expression on the face. The concerns and fears the other person is saying behind the words.

The amazing thing when you truly listen is that the other person knows it, feels heard, and doesn’t feel the need to keep repeating themselves, taking up more and more time as they try again and again to be heard. You will also notice when you listen in this manner, it takes an enormous amount of mental focus and energy to sustain. Listening is work!

One mental technique that can help is to imagine a clear dome over the two (or more) of you as you listen. Everything outside the dome is unimportant (no more checking your watch or looking at your phone.) Everything inside the dome is important. No more capsules keeping us apart. We are together in this communication. You make yourself 100% present in the moment. You let go of your own agendas and intentions to influence, control, or direct. You are simply and profoundly listening.

According to Doreen, leaders who learn to listen in this way are rare. But those who do inspire greater trust and enjoy greater mutual respect. In addition, they arouse not only accountability, but loyalty. You develop trust in a more profound outcome, rather than trying to control others or have your way.

My guess is true listeners spend much less time rehashing the same old, same old, therefore wasting less time in unproductive meetings and conversations. I encourage you to try it for yourself; start with one or two conversations today and truly be present to listen to the other person. I would love to know how this feels and whether in the end it is worthwhile.

Doreen Johnson can be reached at her website: www.riverdreamsintuition.com

A Technical Writer creates and compiles a range of documents. This is especially true when the product involves multiple divisions, departments, or projects. By working across these multiple channels all knowledge gained will be incorporated within several documents. Product specifications, deployment manuals, instructional material, operational manuals, forms manuals, brochures, etc., may need to be written. Within each document, the Technical Writer will communicate what is relevant and be able to present it in a creative manner. Creativity is important when constructing tables, charts, graphics, or diagrams to simplify and enhance details of procedures, processes, business reports, etc. Besides relevancy and creativity, there are other core requirements for specific types of documents. Below are some standard forms of documentation frequently generated during a product’s life cycle. Under each type of document are some fundamental elements.

Requirement Documents (created at the initiation of a project) contain:

• Date and authorization,
• Project scope/overview,
• Task proposal,
• Proposal validation,
• Business goals,
• Specifications,
• Time and expenses,
• Resources and support.

Software and Functional Specification Documents (created for Developers and Analysts) contain:

• Technical details of the product,
• Detailed tasks,
• Database design and schema location,
• Client needs,
• Program functionality,
• System platforms ,
• User Interface,
• Security,
• Error messages.

User /Operations /Training Documents (created for guidance and instruction) contain:

• Guide description,
• Product description,
• Installation and/or log-on procedures,
• Program functionality,
• Required information,
• Prompts and error messages,
• Trouble-shooting section,
• Glossary,
• Reference sheet.

Reference/Cheat Sheets (created as a quick look-up) contain:

• Brief program overview,
• Brief explanation of each functionality,
• Quick ways to accomplish a task,
• Brief trouble-shooting section,
• Index and cross reference sheets.

Quality Assurance/ Test Plan Documents (created for testing) contain:

• Program description and client needs,
• System requirements,
• Program accessibility,
• Functionality,
• Tasks and scenarios,
• Expectations,
• Regression testing,
• Problems and resolution.

SOP (Standard Operating Procedures) Documents (created for routine tasks) contain:

• Purpose,
• People involved/affected,
• Guidelines,
• Revision instructions.
• Procedures,
• Appendix,
• Glossary.

Each of the above documents will be elaborated on in future posts. There are many other types of documents that a Technical Writer produces. The above were selected because they are generally the most common. If there are others that you wish more information on, please leave a comment.

Communicating on the Internet allows you to be part of a community and along with that stems network etiquette rules. Corresponding, writing, or having a conversation on the Internet is no different from having a face-to-face conversation with someone, except that your dialogue takes place over a network. Because a conversation takes place over a network, the standard conversational etiquette rules have been expanded to Netiquette rules.

Some basic ‘Do Not’ guidelines are:

• Do not be rude via the Internet nor email. There are a number of communication avenues, i.e., posts, Facebook, Twitter, etc. No matter which method is used, people should be cordial and respectful to whom they are writing. Would you be happy if someone sent you a critical or cutting remark? As the saying goes, ‘If you haven’t got anything nice to say, don’t say anything’.
• Do not pass on other people’s information. No one is allowed to pass on a person’s information without the approval of the individual. This is a crucial rule to commit to memory especially if you are thinking of passing someone’s personal information. This could lead to a serious offense, so do not even consider it.
• Do not use all capitals when writing as its connotation implies yelling. Bear in mind that the reader cannot see your face and can easily misinterpret its meaning. Appending an emoticon to the capital letters to imply a tease could even be misconstrued as a sarcastic remark. So pay attention to the use of capital letters and only use them for, e.g., acronyms.
• Do not change someone else’s words. What a person writes belongs to them. Do not change someone’s content to be spiteful, harmful, or hurtful.
• Do not send chain letters nor inappropriate links. Not everyone enjoys receiving chain letters. This will just annoy the receiver. If you send someone a chain letter and they respond to you with a ‘please do not send’, then respect their wishes and do not send anymore.
• Do not send spam. Spam is any unwanted email. Set your email options to forward all spam email to either a spam or trash folder where they can all be deleted without any harmful effects.
• Do not spread private chats nor conversations. This is a malicious offense. The conversation you have with someone is private and should remain as private unless they say it is ok to pass the conversation to others. Not following this rule can be damaging and libelous.
• Do not continuously send chat messages to someone who does not reply. Seeing someone on chat doesn’t mean you have to speak with them. Be respectful- if someone does not reply on chat, then they are probably busy.
• Do not send out an email to everyone (i.e., co-workers and managers ) and do not click Reply to All if only one person needs to be the recipient. This is especially true if the other people are not involved with the subject matter. This will only displease fellow associates as they probably receive more emails than they want on a daily basis.

The key rules to remember are to be responsible and respectful. You are accountable for your actions as well as for what you write, so make note of the ‘Do Not’ rules.