Author: Theresa Pojuner

You are gathering notes at a meeting for a group of documents that need to be produced. Are you listening to the individuals as they speak? Are you really hearing what they are saying? Not only that, are you writing down what they are saying? What is the meaning behind what they are saying? Are they being specific or general?

You will be the author of many documents and have to handle many different scenarios and have to be able to transcribe what you hear.

• If someone is speaking on subjects that are scientific, technical, or analytical in nature, then describing what is being verbalized, is probably straight forward to follow. (That is, if you are familiar with the subject and are able to ask questions later on functionality, expertise, and quality of what is being shared.)
• If someone is speaking about businesses and what they want developed, can you read between the lines and understand them even when they cannot verbalize what they truly want? If you cannot, then you will have to try to find answers from an assistant, a subject matter expert, from researching online, or from someone else that is familiar with that person or business.
• If there is a conflict and you have more than one person yelling about a process or topic, then it’s more about who is being the loudest in the room. At this point, they just want everyone to focus on them; to be the main speaker. Then what do you write?

As a writer, you have to listen to what is spoken, and most importantly, what they are not saying and then translate that onto paper for verification.

This brings me to semantics. The Merriam Webster dictionary defines it as ‘the study of the meanings of words and phrases in language and the meanings of words and phrases in a particular context’.

You’ve heard the saying ’it’s all semantics’. The phrase usually means its words referring to the same meaning. But do people really mean what the words portray?

How you phrase words or use terminology is very important when it comes to technical writing and communicating. Defining technical terms is like defining mathematical values. If I say I am displaying ‘2’ icons on a screen, then I mean, I am only displaying ‘2’ icons on the screen, and not ‘1’ nor more than ‘2’. There is only one number and one way to state it.

When you are told (or instructions have been written) to cancel a script, do they want you to stop it and dismiss it for now or terminate it permanently? If the verbal (or written) instructions say to cancel and delete, the operator would know to stop and remove it.

Instructions are not like semantics. Instructions must have very distinct meanings. So be careful when you are communicating. Be as precise as possible, and if need be, use pictures to help describe what you mean.

Once the context is fully written, described, communicated, and confirmed then it will be complete and accurate.

If you have ever run into situations describing terms with double meanings, please leave a comment. Also how did you rectify the situation? Thank you.

 

You are at a meeting to help set up a project plan for a new undertaking. You have been asked to estimate the time needed for your documentation role in this particular project. How will you know how long it will take to complete the writing project? You could have researched before the meeting and studied previous project timelines, reviewed them, and then apply the same length of time (or you can adjust the timeline accordingly). If you were really organized, you could have created your own timetable and therefore be able to give a more accurate account when replying.

To create your own timetable:

• Make sure you have kept a schedule of events and tasks and how long it took to complete previous projects; include benchmarks or target points as check points to see if you are on schedule.
• Be sure to also indicate any resources that aided in the development.
• Note any interruptions such as changes, updates, deadline movements, etc. that would affect deliverables.
• Check availability of subject experts to gather information from.
• Ensure the right tools are available to you.
• Verify certain key dates with team members; such as when requirements, technical, training, etc. documents have to be done.

Also ask the following questions before replying as the responses might affect your schedule:

• What is the purpose of the documents you are creating?
• What types of documents are needed?
• Has a pre-arranged date been set already? – Or do they just need a date from you.
• Who are the stakeholders and will they need to approve the final documents?
• Will any previous training be required?
• Will translation be needed if this will also be a global document?
• Who is your audience?
• What format is required or can the standard organization style guide be used?
• Will images, videos, etc. – any medium other than text be required for the project?

Creating a set timeline is not an easy task. Too many factors can affect the final deliverable date. So what should you do to try to avoid a missed date? Ask others at the meeting their opinion; what do they think of the timeline? Do they see anything that might affect what has been determined? Even though you are experienced, there may be other events in the works that you are not aware of and that might affect your outcome. So ask.

Also, as a final statement, create contingency plans. Even though you may have all your key elements in order and approved, you never know what else might pop up to interfere with your schedule. So make fall back plans for those ‘what if’ cases. Oh and one more item. Stay focused and monitor the workload and schedule. If either of them are out of line, then be prepared for unforeseen events to occur.

Good Luck on pin-pointing your project date.

If you have had problems setting project dates and keeping to them, please leave a comment.

What do you do when you are working in a chaotic organization and there are no guidelines and no procedures nor processes to follow, and you have been assigned to create documents. What is the first thing that you do?

Research, research, research….find out:

• if any coherent software development life cycle exists; what is the current procedure or routine
• all the information you can about what documents currently exist and ask questions as to who, when, and how the documents were created. Note – when reviewing pre-existing documents try to find out all you can about the previous writer – it could be that it was created by a developer, analyst, or manager; whom may have more valuable and detailed information for you.
• who’s in charge and how do they keep track of events, the project goal, or changes and updates
• how things are currently done; that is, who does what,
• who makes the call for changes and how are they directed to the right resources and is there any existing documentation of changes and what the changes affect

Tips on trying to get organized:

• If there are no preexisting models, flowcharts, nor processes, create one by first interviewing the project lead.
• Attend all the meetings that you can and also hold your own meetings and find your subject matter experts. Make sure you are on the list of attendees for all meetings. Also make sure you are invited to every brain storming meeting for new projects.
• Maintain communication between the team leaders or members.
• Get assistance in creating a notification program or system routine so that when a change occurs, you are also notified. If an internal program cannot be created, ask to purchase a tracking system.
• Create a guide for yourself and for those following you. Include all that you have learned to make it easier for you and for anyone following you.
• Make note of everything you have discovered and keep yourself organized even if the company is not.
• Use your left brain and be methodical when creating folders and sub folders of projects and related documents.
• Create your own project plans and add it to any existing plan.

To help stay organized, begin your necessary documents as soon as you can to stay ahead. Plan ahead and create contingent plans for any unexpected delays and bottlenecks, and ensure that all problems are resolved. When planning out documentation projects, besides analyzing project requirements, identifying types of documents required, selecting resources for writing and gathering data, and setting milestones, also make sure you have the right tools available and the budget required to complete the project.

Once you are satisfied and have analyzed the project requirements, set milestones indicating critical dates, estimated the budget that is required to complete the project, identified the types of documents (as well as format) required for the project, selected the appropriate resources (in source, outsource) to gather data, you can create the content. Ensure that the right tools are available. If you are a lead technical writer, determine whether or not any assistant writers require training or need to be re-trained.

You are in essence at this point acting as the Technical Writer Project Manager and you should be congratulated for that.

Your knowledge stars or SMEs (Subject Matter Experts) are your most important assets when it comes to getting the information you need to fulfill your requirements documents or any other documents that are being written. They will supply you with all the information needed to understand the product or processes, and teach you to be knowledgeable about everything from its functions to its drawbacks so that you may be able to write and convey its benefits, values, requirements, constraints, limitations, etc.

A good Technical Communicator /Writer is able to interact with and question the SME’s involved and will always take the initiative to perform some research as well to seek out more knowledge about the items that were discussed at meetings and to ensure validity and execution.

But where do you find your SMEs?

• For resources – ask at the meetings. Ask specifically who will be the Developers, DBAs, Testers, Lead Project Manager, Sub-Contractors, etc. Also double check the requirements. If incorrect requirements exist, then the wrong resources may be selected
• For product information – you can begin to investigate on your own about the product and when asking questions, you will find more knowledge stars to assist you.
• For timelines – seek out all stakeholders to find out specific dates and confirm that each stakeholder is aware of what the dates are; coordinate with them to ensure accuracy of timelines.
• For the scope of the project and the path that it will take to be completed; ask and confirm this in writing to all stakeholders; specifically managers, and clients. They will notify you with any inaccuracies.
• For maintaining accuracy – the Technical Communicator has to be flexible enough to stay on top of all changes. Set up a system to track changes. Changes include and are not limited to updates to the application/product, The Technical Communicator also has to stay close to and be aware of changes regarding SMEs, management, resources, timelines, etc.
• For security issues – check with your managers and IT personnel and question them about confidentiality, maintenance, issues, protocols, archives, contingency plans, etc.
• For marketing – seek out all marketing stakeholders and ask about any training or documentation (user’s guide, training manuals, advertising material) needed or previously used.
• For Policies and Procedures – seek out your HR personnel and also include these as questions when gathering your information from other employees involved in ensuring control over processes, giving directions, setting standards and following them. In other words, maintaining compliance or preserving requirements. Make sure all the rules or guidelines are uniform and consistent. Also check the SOP (Standard Operating Procedure) guide. It’s possible that what you seek has already been written in an existing document.
• For day-to-day information – a really good resource is your Customer service personnel. They are directly involved with the customer and have dealt with problems and resolutions. A lot can be learned from them.

The approach I like best is to create your own brain-storming sessions. How have you been able to seek out your knowledge holders? Please leave a comment.

1. Not knowing your audience and stakeholders – not knowing your audience could mean not only presenting unnecessary and non-essential information, but possibly also presenting it in a manner that the audience does not understand. If a document presents unfamiliar or foreign terms to the audience, then the material is not helpful nor constructive.
2. Ignoring your SMES – find your SME’s (Subject Matter Experts) – listen to them and find out any information you need to complete your documents correctly. Not gathering the right information and not paying attention to updates is not an option. Any misguided information can be disastrous to your audience.
3. Not preserving privacy – not understanding nor maintaining confidentiality of information can be detrimental to an organization. Make sure you know which material has to be handled with discretion.
4. Lacking organization – stay organized, methodical, and in control. This will help you keep your documents organized as well. Make sure there is some logical order to the material as a whole. Do the same within each section of the document. Provide indexes and a table of contents so that pieces of information can be easily located.
5. Underestimating time – not estimating the right amount of time for writing can make you rush and produce a sloppy document.
6. Not being consistent – too many styles and fonts can be confusing for the reader and be visually tiring to the eyes, respectively. You want them to see and absorb the information; not ignore it because it is visually unappealing. Also, be consistent in writing and in how you present your information. The same goes for images and pictures as well – label figures consistently so they can be easily located and followed.
7. Ignoring comments or feedback – do not ignore any comments regarding your writing and presentation. Listen and understand what they are saying to you. They are only trying to help make a more useful and better document. The suggestions may help to provide better readability, flow, or layout.
8. Being too verbose – documents provide a clear and precise presentation – the audience does not determine if the document is good or bad by the number of words that are written. Write what is needed.
9. Lacking images – provide images whenever they are needed to enhance what is written; these are especially needed when giving instructions to perform a crucial task. When describing a whole system, create a system with a top image and then break it down to the most basic components – like a hierarchy.
10. Most importantly not creating backups – forgetting or not creating backups is a disaster to everyone; especially the creator. Make sure you add it to your checklist as one of the essential items to do. Not only is it tiring and frustrating to recreate your work, but it never is the same as the original that was created.

What other fundamentals should be avoided when creating documents?

 

Writing status or progress reports are not fun, but are a necessity. It’s like going to the doctor for a checkup – it’s not fun to go, but it’s a must-do necessity to see if you are well or not. Status reports are a way of communicating to the managers, clients, and stakeholders the state of a project – good or bad.

Purpose

Status reports not only give you a view of a project’s current state, but also what has been achieved, and what has to be achieved – it provides a summary and aids in maintaining some control or management over a project. These reports help by presenting a good idea of what ‘next’ steps need to be taken till project completion is reached.

Beginning

Before you begin the status report, make sure you are well-informed about the project’s business scope so that critical stages can be listed and prioritized. Hence, the status report can include (when necessary) items such as, whether or not there have been or will be issues involved during those critical stages to affect the project either negatively or positively.

Suggestions

• To make creating the status report easier, components can be derived from the project plan. Next, provide additional content or expand on the essentials. If you maintain and/or schedule the status report in the same sequence as the project plan, you can easily see what stage everyone is at within the project, i.e., the status of everyone’s tasks. Any additional items listed in the status report can also be gathered from the requirements document as it will note items such as cost, as well as, e.g., issues or concerns from those involved (resources) to equipment (software/hardware), etc.
• To ensure that you have included all necessary items, create a checklist
• To keep all stakeholders informed, the status report, should be written either weekly or biweekly. How often you create a status report depends on the magnitude and length of a project as well as what’s involved. For example, short-projects and some long-term projects can require a weekly status report. (Long-term projects involving, e.g., major financial subjects may require weekly status reports instead of biweekly.) Most long-term projects require biweekly status reports; especially if time is needed for research or a significant amount of programming.

Format

The status report should always have a consistent format for ease of readability, thus allowing readers to easily pinpoint particular information, such as, whether or not the project is on schedule and on budget. For example, depending on your format, critical issues such as scope changes can be noted in the beginning, and resolved issues can be noted towards the end of the report.

Preparer

The status report cannot be done alone by the project managers. They need input from all project team members. Each member involved from inception to completion (from technical writer to tester) should be required to provide a status to the project manager, who will then gather and assemble all the information. Formal status reports are not needed from all team members; e.g., some programmers can just send an email or verbally state what they are currently working on, what they have completed, as well as their concerns and issues during their weekly/biweekly status meetings.

If you have had to create status reports, what else is needed?

We have all attended quite a few webinars, events, courses – some very good and some not so good ones. In comparing them, were the good ones due to communicating knowledge well and the not so good ones lacking in communication and knowledge?

The good communicator – Prepares for the topic ahead of time. They also begin with:

• a solid introduction, by giving a heads up to the attendees of what the event will consist of,
• what will be presented,
• when Q&A occurs,
• finds out the level of knowledge of attendees,
• what attendees expect from the speaker,
• manages time accordingly,
• maintains a high level of energy and demeanor, and
• shows no frustration shown by the audience.

The not so good ones – lack all or some of the above attributes when it comes to speaking and presenting the course. The presenter is there to help the attendees, not to frustrate them. The attendees are there because they are somewhat frustrated by a lack of knowledge in a certain area, and the presenter is supposed to fill that void.

Therefore, to succeed:

• What is highly needed is knowing the subject matter. Even if you are a great communicator, if you do not know the material, and some extra knowledge that allows you to answer questions, then a successful session or lecture will not occur.
• Using a few ‘umms’ – sometimes a speaker cannot help but do that even when they are knowledgeable when they are nervous, but as they move on and the audience is attentive, then those ‘’umm’ moments will cease.
• Lecture at a normal speed – speak as if chatting with a friend – then the audience will be able to follow the lecture. Too slow will be boring and put them to sleep and too fast will not allow the audience to absorb what is being said.

To help the presenter, it is always good to also supply the audience with some documentation; either a quick reference sheet, or an outline of the presentation. This way, the audience feels more connected to the subject as well as the speaker, and will not feel that they might get lost.

Other ideas are;

• For important ‘how to’ steps, the presenter could demonstrate processes whenever possible and supply links on the sheet that will redirect them to review what steps were taken.
• For further reading material, as well as more tips, the presenter again can supply a link to some manuals, documents or resource material and reviews that consists of more detailed information on the subject.

When it comes to Q&A time, always listen and try to understand what the real question is being asked. If the audience is enjoying the lecture, individuals will assist and reword what is being asked so that the question can be answered appropriately. Also, if an answer is not known, then there is nothing wrong in saying, the question will be looked into and a solution researched.

So to answer the original question of ‘..were the good ones due to communicating knowledge well and the not so good ones lacking in communication and knowledge?’.

The answer should be ‘yes’ to both questions because there is a distinction between what is a good communicator and a poor one. It depends on the amount of knowledge presented, the ability to answer questions, and listening to the audience.

When presenting documentation for approval, adjustments have to be made even if there is a set standard and style guide that lends itself to mold out documentation in a unified format.

Sometimes you have to make the adjustments and customize for the client, as not all clients are the same. They may prefer different ways to present what they want, especially to their own stakeholders, employees, or clients, etc. They may accept your explanations or reasoning behind what is presented, but they know their stakeholders best and may say ‘yes, ……’but’….For cases like these, bend the rules and go with whatever the clients wishes, as in the end, it is their choice.

They know their business better than you do and know how the business operates better than you do, so let them finalize, revise, organize, and handle their own forms of written communication. They may have their own communication department and their own standards or traditions to abide by; in other words, they have their own branding to maintain.

What I just described probably falls in the arena of a technical writing consulting communication position. The basis or foundation that you offer can be provided, but then in the end, it is up to the individual or company that you are working with or for. Some companies may just accept what you present and like it. But just as a precaution, prepare for more than one presentation. Be adaptable. Be prepared to change paths as you are speaking and presenting to them. The best way to accomplish this is to rehearse prior to communicating with them and play out different scenarios in your mind ahead of time.

Have you seen that show on television where improvisation takes place? Well you should apply the same techniques when you can. If you are relaxed and are confident and knowledgeable about your work, then you will have no problem. I find that if you are happy or have just laughed at a joke, then you are in a good mood with endorphins rolling in and will have that extra confidence. The audience will like how you are speaking and smiling and thereby exhibiting a lot of energy and vitality. It in turn puts the audience at ease and in a good mood. As a result an informal Q and A can occur where energetic atmospheres are brought about and in turn allows for a- good brainstorming session as well. When this situation arises, more creative ideas can be brought forth.

Even if you think you know your audience pretty well, they may have other priorities or a different agenda that they have to stick to. So when presenting your documentation, have available with you various documentation formats to see which the audience prefers. Be adaptable, confident, and be prepared and ready.

If you have had to make a presentation and have experienced being adaptable and making last minute adjustments, please share your experiences.

You are going to give a presentation on a new application or product. There will be stakeholders, developers, and some managers at the board meeting. Your hands are sweating and you are short of breath. Do not worry – you are ready. Why? Because you have all your notes, and your presentation is ready. You have created a slide show with outlined material, and you have a binder neatly packaged with information to hand out. The packaged notes are very important, especially for those who may not be able to stay for the complete presentation.

Be aware that your audience may be varied, and may not be familiar with the project, so add in some extra background information to ensure everyone is brought up-to-date. And, to ensure that you have all the necessary information and material that you need, make sure you have documented and included the following:

– An introduction to the new product and its purpose, the reason why this project is needed, and how it benefits the organization.

– Material supporting your work on Identifying, assessing, and analyzing all the business requirements, processes, and risks involved, and your ideas on the best way to present the results.

– Notes on continuous meetings with all stakeholders (managers, developers, users, etc.) and how you have collaborated with others to develop some business cases.

– Time, cost, and resources it will take to reach the end result.

– All the technical and functional specifications; guidelines.

– All the technical information detailing the system and data architecture including taxonomies, metadata, definitions, monitoring, recovery solutions, etc.

– Handouts describing specific topics at a high level and then a breakdown for others.

– Images of prototypes.

– Compliance issues.

– All the required test and regression test plans and respective scenarios.

– What user manuals, lessons, training material will be required and what user support will be needed via customer service.

– All the needed marketing and sales material.

– And finally, an appendix, glossary, reference sheet, etc., if needed.

Create indexed sections for all of the above for easy reference. Be creative and include some tear-out sheets for referral. You can even include a link to the existing packet you are handling out for easy referral. Create mappings, charts, etc., to depict as much information as you can. Include your slides in the packet so that the audience can jot down notes. For the style of the referenced material, use bullets and outlines, or list items for an easy read; shorten verbiage.

For a break, questions can be included at the end of each of section to jolt or remind the audience to consider other additional questions to ask, or to provide recommendations or insights.

Please leave a comment if you have ever had to create a portfolio or a presentation package. What were the drawbacks and benefits?

As an addendum to the previous post on Tips For A Training Manual, I have to add that communicating information face-to-face is difficult and is even more challenging when you communicate via text. Whether you are writing user manuals, online help, technical documents or release notes for software applications, you need to have certain attributes to be an effective Technical Communicator. Attributes such as:

1) Having technical excellence in understanding the product. The Technical Communicator has to be knowledgeable about the product; its functions and fall-backs in order to write and convey its benefits, requirements, etc.

2) Being analytical and logical (in order to explain soundly what is occurring; the why and the how). This is exceptionally needed when performing quality assurance tasks or creating test plans.

3) Understanding the organizations surroundings or the environment; its culture. The writer has to be alert and be able to use intuitive feelings to see and grasp certain conditions or situations to communicate what is needed; a content strategist. An example is when an organization does not realize that additional types of documents are needed, e.g., when a company with many writers in different departments would benefit from a style guide.

4) Being aware of the user’s experience, i.e., how they can use the application software or product. With this in mind, it’s not just, e.g., describing how to navigate from one screen to another. It’s about clarifying and detailing what the user needs to know, as well as taking into consideration how users operate.

5) Understanding the client. This attribute is especially needed within global organizations to prevent misunderstandings leading to product errors.

6) Understanding the SME (Subject Matter Expert). This is crucial for being able to translate details, e.g., business processes or data requirements.

7) Having interviewing, listening, and collaborating skills. Knowing how to paraphrase a question to get the appropriate response, understanding what is being conveyed, and being able to interact with individuals to gather your data, respectively, are necessary interpersonal social skills

8) Being organized. Managing and keep track of all the information that needs to be explained is not an easy task. Being methodical will aid in creating structured concise documents.

9) Being a designer. Technical Communicators are visual designers too. They have to be able to know the audience well enough to customize and present the documents in an appealing creative manner.

10) Writing capably. Writing is not just about grammar and vocabulary. To communicate technically via writing, the information has to be detailed, clear, concise, and complete.

11) Being adaptable. Having flexibility is needed for last minute changes and for cases when unforeseen events cause new incidents. Constant changes occur all the time. The communicator has to be flexible enough to accept these changes and to make necessary adjustments. Being adaptive is also being able to adapt to how you relate to your audience.

Bringing all the above together, presents an effective Technical Communicator.

What other attributes would you add to be an effective Technical Communicator?