Author: Theresa Pojuner

How does a technical writer and developer communicate how a product works to a user? How do they communicate functionality, to make their audience’s user experience easier? They plan it out by knowing their audience, knowing what is expected of the product through meetings and through training.

Knowing the audience

Create the product needed by the user.

• What does your user need to know- what do they already know?
• Does the developer know how much information a user knows and more importantly, what is needed by the user in order to develop applications that are suitable for them? For example, do menu options need to be displayed?
• Does the technical writer need to write lengthy documents or just quick sheets?

Knowing what is expected

The answer to many questions is by having all parties share their knowledge through meetings. The technical writer, as mediator, interviews each party, and gets answers to questions, such as:

• What will the product do and why?
• Will the product be suitable for the user?
• Will it be intuitive or data driven?
• Will the technical writer have to write a long procedure?
• Will this be on the web? Web-based applications are easier for users to access and use. Documentation will also be easier as help menus (with hyperlinks) can be created.
• Will this be an end-user product? – If so, then documentation will be lengthier unless the product is easy to use and mostly error free. – Note: To avoid frustrating user errors, multiple options can be listed to avoid this problem.

Knowing what training is needed

The best product or application for a user as a whole should not be complicated.

• If a product or an application is complicated or has a lot of options, then the technical writer can develop business cases with user stories to help with explanations. The writer can also create training sessions with demonstrations and/or create instruction videos that are not too complex. Images are always better than words. Words however should still be written to reinforce what was presented.
• If an application is, for example, a data entry form, the user should be able to go through the mechanics without problems – in other words, it should instinctively lead the user to the next screen or item without any extra work nor thought from the user.

Key words are: ‘what is needed, shared, and not complicated’. To communicate functionality to the user, know what is needed, be aware of what they already know, and know how best to present it. Make sure that communication exists between all parties through meetings. Knowing how much to document will also depend on the results of these meetings. As always, when verbally communicating or writing, stick to the point; be concise and accurate.

If you have any suggestions or comments on how to communicate functionality to make a user’s experience more enjoyable and easier, please leave a comment. Thank you

 

 

 

 

Technical Writers describe error messages that appear within many documents and applications. They are useful, necessary, and required. Without these warning messages, readers\users would not know that, e.g., an incorrect key was pressed or that some information was missing to complete a task. Error messages describe what to do (or not), what information is required, or whom to contact to correct a situation.

Error messages exist within documents, such as:

• Technical Specifications which developers use to program and present different types of error messages indicating where, when, how, and what.
• Functional Specifications which describe expected error prompts and information required to complete tasks.
• User Guides which warn users by defining errors (what to expect – where and when) if certain prohibited tasks are done and how to correct the problem.
• Ready Reference sheets which list commands as well as what errors might occur, what they indicate, whom to notify, and how to correct certain problems.
• Test Plans which help locate problem areas.
• Bug lists (or List of Errors form) which contain anomalies from testing. e.g., while performing software testing to identify defects flaws and errors in application codes, the detailed steps that led to the errors are noted here. Without this completed form, developers would not be able to replicate the occurrence and hence correct it.
• Feedback forms which include questions such as ‘Who is not satisfied with the document and Why’. Asking appropriate questions help to find problem areas, e.g., material was written for the wrong audience, contains incorrect or bad formats, or has errors.

To prevent errors within a document:

• The front matter of certain documents should present a list of readers/checkers approving the document, thereby ensuring its completeness and accuracy. This will avoid problem areas, i.e., missing tasks within an application, missing reports, incorrect data, etc.
• The material should be produced as a technically accurate document.
• The contents of global documents should be examined and presented as a clear, concise, error free
• The writer should be vigilant and, put themselves in the shoes of the reader, and maintain direct communication with stakeholders.

Error messages are also written for:

• Developers to ensure that accurate data is located, gathered, and present a clear understanding of data repositories.
• Disclaimers to avoid liability for errors or omissions.
• Data analysts to investigate data discrepancies and to detect and resolve errors.

Benefit of Errors:

• They help to teach, especially when using animation to display problems and resolutions.
• They help to maintain and manage accurate data.
• They help to provide editing and proofreading for grammatical errors.

The Technical Writer must ensure accuracy, completeness of technical documentation, and meet company standards, even when providing error messages. Technical Writers are also editors when ensuring documentation that is error free in content and in the usage of grammar, spelling, etc. This is especially important when producing material (i.e., marketing, training, global, or compliance documents) that reflect upon a company’s image.

As Technical Writers and Communicators, we have to communicate and collaborate effectively. If we follow some basic rules about interpersonal skills, then we can be sure that communicating verbally and in writing to individuals will be successful. How do we begin to do this?

Build your relationships. Make sure that you are paying attention to others when they speak.

• Pay attention and face them when speaking and listening.
• Show them that you genuinely care about what they are saying by nodding or smiling.
• Repeat what you heard to make sure that what was said is understood and verified.
• Avoid miscommunications by taking good notes. But try not to look away from the speaker too often when writing down notes.

Build a rapport in order to exchange information more easily.

• Pay close attention to what is being said and listen to what they want and what they know.
• Be honest and open when speaking about any information that is shared or needed.
• When sharing information you have, be open and trustworthy.
• There is no need to hide nor hold anything back if all the information is factual.
• Answer questions truthfully to form a trust.

Make the conversation data driven.

• Have your data ready for a presentation or to make a convincing argument.
• Use it to help display points. Data is factual and real. Once shown and explained, information will be more easily understood and retained.
• In addition, provide visual images to represent data facts. This helps others to digest information more easily.

Engage others to join the conversation.

• Taking advantage of relaxed encounters can cause people to open up more and hence reveal even more information or details.
• Opening up communication within a group can provide more ideas and questions that need to be answered.
• Having others give their opinions and thoughts can open up new topics from rethinking and ironically, open up more challenges. This latter item is a good thing not a bad thing as it motivates others to delve into other areas. Innovations, improvements, and increased productivity can surprisingly, result.
• Engaging others can also provide new designs, concepts, and views.

When having a conversation involving more than two people, there are precautions that have to be taken. This is the case when one person dominates the conversation – do not let this happen. You always have to be in control if you are the originator of the conversation (and/or meeting). People can diverge from the main focus of a topic, causing the reason behind the conversation to be lost. Try to keep conversations (and/or meetings) on task.

In the end, workers and coworkers function better when working with people they are comfortable with. So it is best to be interested in the people you are communicating with. Information will then flow easier as well, i.e., a relaxed interaction allows better collaboration and more information to be shared. Building personal relationships is important for helping to get your tasks and hence your writings completed.

How does the Technical Writer or Communicator document a network of machines that communicate with one another? Documenting even a small company’s network on how its machines communicate or transmit information or data can be a challenging task. This includes learning and describing how each piece of equipment operates.

The Technical Writer has to know how each machine functions and know its varied components. The writer also has to understand how the machines communicate among themselves and to humans. The machines can consist of any of the following – backup systems, servers, laptops, peripheral’s like printers, ip addresses that identify each machine, protocols that are a set of rules for communicating, its wiring or connectors, its properties, ports, etc.

The following is a list of suggestions to follow.

• First, create a chart of all the equipment within the company and note the location of each. Label everything.
• Second, get a description of each piece of equipment and its functionality.
• Third, get a description of the software involved; set up, usage, accessibility, and maintenance.

Example:

If a piece of equipment is connected to another device via a cable,

• Note its description, location, functionality, and associated software.
• Create drawings, mappings, wireframes, etc. of all the equipment that are associated and located in one area and label each item. In any organization, do this for every piece of equipment and group them into categories.

Creating categories and sub categories.

Break it down.

Example:

If a laptop is connected to a printer via a USB cable, or if the laptop is connected wirelessly, create a category labelled printers. Then create sub categories of hard-wired and wireless printers.

When creating the documentation:

Use diagrams

• Mappings to show functionality within the company.
• Diagrams to show the design and the internal components of each piece of equipment.
• Wireframes for showing the skeleton of the connections for communication.
• Graphics to show the movement or the process for transmitting information or data.

Create detailed documentation, including

• Creating detailed user manuals and reference guides.
• Listing the owners and those authorized to use the system.
• Describing the system features, menus, what to do and what not to do, and possible error messages.
• Describing the hardware, ports, and mechanics of the system.
• Writing about the protocols of the system.
• Describing how the information is transmitted, and how the machines communicate with one another.

Pages and pages of diagrams and documentation can be created, but it can be simplified. Break it down by categories, such as regions, or procedures and processes. Create a hierarchy from the top down. At the top, state the goal. Then, as you go down, break it down by systems, then applications, then processes, then hardware, etc. till you get to the bottom where the intricacies are denoted and explained.

If you have had experience documenting a network of systems, and wish to add to this topic, please leave a comment. Thank you.

Release Notes are often written to communicate software or product updates. They define what is new. Release Notes allow us to manage, announce, and activate any new hardware, software, application, product models or devices.

Release Notes include:

• A history – state why this document was created.
• Version # – state the version or control number and what original project it was a part of and other documents involved.
• What requirements are needed – state application software, hardware, data, etc.
• What is new – state all the new features. List a comparison to the old to make it clearer.
• What was modified – state the reason behind the modification and state the new changes that were made. The product could have been too complicated to operate so steps were taken to make its function simpler.
• What was removed – state what originally existed and why it was removed. It could be because the usage was no longer valid or out-or-date or something new was created to take its place.
• What was added – state any new features or what was added to make the product better and more useful.
• What was fixed – state what problems or errors were corrected and/or modified. List detailed information if required and what was needed and done to correct the problems.
• What problems were not fixed – state if any existing problems were not corrected and the reasons why they were not taken care of. State a possible date for corrections to take place in the future.
• New installations instructions – state how to install the new product or version of an application, model, device, etc. List instructions step-by-step to ensure accuracy and the reason behind each step if necessary.
• Supporting features – state all other supplementary or beneficial features of the new version, from, for example, adding a new customer hot-line to easier functionality.
• What has changed – state how the new version has been updated. List all changes, its benefits, and the reason behind it.
• What has not changed – state any product features that were not updated and the reasons behind it. Reasons could be lack of time, information, resources, etc.
• What to do – state what has to be done for the new version to take effect or to function.
• What not to do – state what should not be done. This item should be red flagged to indicate damaging, unsafe, hazardous, etc. elements.
• What should be displayed – apply Images (of new items or functions), figures (of new items), charts (of new items and benefits), grids for comparison and bulleted items. Bulleted items help to state details within explanations for easier viewing.

Release Notes are needed to provide information on what items were changed and how to operate and use the new or modified versions of a product. They help to maintain organization and to manage operations within any industry.

If you have created release notes and have more to add, please leave a comment. Thank you.

 

 

 

Communication can exist across all ages despite challenges. Communication can be made easier through collaboration. Communication and collaboration between older and younger (millennium) generations is needed from both parties for transferring knowledge. The millenniums have more technical knowledge and patience to teach the elderly. The elderly have more life experience in businesses and in years that can be shared with millenniums. How do we get communication and collaboration between the two different age groups?

Meet

There are many groups that meet to discuss and share information in all subject areas. People find each other through the internet to meet those with similar interests. The same methodology should be applied in businesses.

Example 1

Senior Centers want to have educational classes for senior citizens on how to use mobile devices and how to create a document on their computer. To accomplish this, the Senior Center could search out schools that can help. The result can be gatherings where high school seniors show senior citizens how to operate their new mobile devices and how to work with an application. Both parties benefit. Senior citizens get to learn as well as share their life stories and students gain experience and knowledge from working with others and/or earn extra credit. No matter how it is initiated (email, phone, etc.), communication and collaboration brings the two groups together for a positive outcome.

Example 2

A new training manual has to be created. What should it entail? Like above, technical writers should follow the same approach for communicating and collaborating to gather information for content building. Technical writers need to email or search out a group composed of varying ages. Why? Because new millennium ideas plus senior experience can add up to creating, e.g., a new design, mindset, or plan. Having a mixed age group allows everyone to share how one learned previously, how one learns now, and how one wishes to learn. With this type of meeting, information and ideas can flow easily between the different age groups. With collaboration, understanding, and agreements, a new way of creating and presenting training content should manifest.

Working Together

• Listening – For everyone to work collectively, ensure that everyone is willing to listen to each other. Keep the meeting orderly and make sure everyone has a chance to speak. Information or opinions from one age group may be in conflict from another age group. But, if they listen to each other and there is understanding without defensive interactions, then goals can be reached. Listening = Learning; both are important.
• Learning – Have top leaders communicate the importance of learning for all employees throughout the organization by creating a learning environment

Whatever the goal, theme, or agenda of an intended meeting, the interaction of different age groups can be beneficial and present something new.

If you have other methods for gathering information between varying age groups, please leave a comment. Thank you.

 

 

 

 

 

To be a good communicator, a technical writer provides accurate, reliable, valuable information within documents. Once all information has been gathered, how do you begin to organize it all? You have been jotting down all your notes into a book or a document. How do you de-clutter and pick only the most relevant information that needs to be communicated? Here are some ideas.

Classify It

Arrange the data into groupings or categories.

• Within all your information, if there is one subject that constantly stands out, make that a category, and group all appropriate notes into that category.
• Simple examples of categories could be ‘Procedures’, ‘Graphics’, ‘Reports’, etc. You could also just group all your ‘Red flags’ into one category and add it to an Appendix.
• If no topic stands out, then take one piece of information and see if you can build upon it with related notes that have been taken. In other words, start small and build upon it. Put a category name to this group of information, such as ‘Background Information’ or ‘Must Know Information’ and create an Addendum section.
• For information that you cannot group within any category, create a Miscellaneous grouping. You can add this information to the end of the document as an Appendix or Supplemental section, or it may not be needed at all. But in any case, do not automatically delete it as it may become useful later.

Organize It

Consolidate and organize the categories.

• Arrange and organize the above categories by topic or subject matter into a logical sequence. These can be your paragraph lead-ins or your section headings.
• Build your content within the groupings to create the document.
• Analyze your content to make sure it is valuable and beneficial.
• Create more than one document, i.e., one for managers, one for users, and/or one for developers, marketing, etc., if needed.

Manage It

Ensure that there are no ‘oops’ in your information.

• Delete any out-of-date or obsolete data. Ensure that your data is accurate and precise.
• Collaborate to ensure notification of any pending or possible changes. Hence, be flexible and monitor all your incoming information for updates.
• More importantly, make sure you are more than familiar with the product or application you are writing about to ensure continuous accuracy.
• Create a reference sheet (a useful collection of convenient and relevant information on one page) to direct readers to the appropriate document and its location. Manage and organize it for easy accessibility for all those that will need the completed document.

Notes:

• Readability – ensure that the document reads clearly, smoothly, meaningfully and without any inconsistencies or ambiguities.
• Document the procedure used to de-clutter your notes for future usage.

If you use other methods to de-clutter your notes, please leave a comment. Thank you.

Technical communication must consist of continuity. Continuity is a link from one thing to another. Whether continuity is applied in writing or speaking, if it does not exist, then readers, listeners, viewers are at a loss. Continuity provides readers, listeners and viewers, with clear, consistent communication in learning, understanding, and observing functionality.

Continuity in Writing

Continuity within technical material involves content (including diagrams, images, chapters, explanations, and/or examples) containing a logical, understandable flow of text. Every element has to follow meaningfully from the previous element. Sentences should be complete and make sense. All thoughts and information within each sentence should follow clearly from one to the next. If continuity within explanations, proposals, or objectives are not clear, then misunderstandings and wrong interpretations (with detrimental or chaotic outcomes) can occur within any environment (business, manufacturing, pharmaceutical, etc.). As a simple example of one thing leading to another, if the steps to perform an activity are not in proper sequence then problems and mistakes can occur. Note: Just as importantly, make sure that all the information you have gathered is correct and relevant. Every technical manual should include basic functionality, concise explanations, examples, and references.

Continuity in Instruction

Continuity in instructing your audience or transferring information verbally involves methodical planning and organization. Create an outline so that each detail or instruction leads to another. This way too, you will cover all essential points. Have continuity in outlines for presentations, examples, and activities, by showing how everything is connected or related. Begin with knowing your audience to see what they already know and then provide the information that they need to know. It is a good idea to also prepare ahead for any questions that might be asked. When answering a question, restate the question in your own words to ensure understanding. Then answer accordingly in complete sentences with one sentence leading to the next. Note: Plan so that the appropriate and complete training and knowledge will be transferred to the audience.

Continuity in Videos

Continuity in using video to provide lessons involves each slide displaying a logical progression from one slide to the next. The theme, idea, or aim of the lessons have to follow through from the introduction to lesson 1 to the final lesson. Make sure that one lesson leads to another by making a statement as to what will be coming next in the following lesson. In other words, the end of lesson 1 should end with a lead into the objective of lesson 2. If it does not, then there is a disconnect and the viewers will be confused. Note: Use entertaining or fun videos or emoticons to help in maintaining continuity and to engage the viewers.

Continuity provides a sensible flow for users from reading, to listening, to viewing. It is a link from one thing to another. Without continuity, disruptions, misunderstandings, misconceptions can occur, followed by confusion and mistakes.

If you can add more information to the importance of continuity or have seen examples of material not having continuity please leave a comment.

 

You have a unique idea that would benefit an organization, a client, or management. How do you present your proposal?

Plan It Out.

• Gather all the information you can before making your presentation, and ensure that it is all correct and fits a need. Make sure it fits a niche. Decide if it is something that is required or if it is something that will be a temporary request, wish, or ambition. This will help you in deciding how to set up your presentation.
• Examine all avenues to see if the same proposal was previously considered. If it was, what was the circumstances? Find out why it was turned down or rejected. Maybe you can make improvements on the original idea.
• Test it out and speak with others to see what others think. They might have other suggestions to improve upon your proposal.
• Create a mapping for yourself to see how your idea fits within the realm of the organization or helps to resolve issues that a client faces.
• Create an outline for how you are going to make your presentation and test it out in front of others who also support you.

Upon Presenting.

• First be able to make a beginning statement in one sentence as to what your proposal is about.
• Next state how the idea came about or how you derived at the idea.
• Then state why it is needed. Give an example of how it fills a void, or how it solves a persistent problem.
• Next explain all its benefits. For example, state how in the end, the client or the organization can function more efficiently, or gain more momentum, or reap more rewards.
• Explain how this proposal came about.
• Include with the presentation a slide show, a white board, or video. Make sure that within any of these communication methods, you have captured everything to make the above points and that it shows the objective of the presentation.
• Give out handouts. Include within the handout the resources needed, cost, graphics indicating benefits, etc.
• State how the proposal will be accomplished. List the steps that will be taken to achieve the goal. Include how long it will take to accomplish the task and what resources or budget is needed.
• Create a project plan to include details of the, e.g., development of the product, or the milestones that need to be reached till the end result is accomplished.

In the end, to be successful, be confident when presenting, and make sure that they understand your idea and the reasons behind it, but most importantly, its benefits and its future usage. End the presentation by welcoming feedback. Any comments should not be rejected nor should they be taken internally to lose confidence nor to have misgivings about your idea. Use any negative comments as an experience to be learned, or as a way to see how you need to make changes to your proposal to make it better.

Do you have any other ideas to add? If so, please leave a comment.

As a Technical Writer, communication can be difficult if ambiguous responses are received. Such as is the case when trying to find out information. It can be difficult when someone has a new product, and cannot explain nor describe it. When encountering such a person, you will probably see that they are thinking of one thing, but their words do not describe the thought. They want to make a statement but the content is confusing or seems wrong.

Example:

Someone once told me to think of their product as a puzzle. I assumed then that the product was something like a puzzle. But in actuality (after quite a bit of questioning), they meant that they think of their product as a puzzle because they don’t quite know how to explain its functionality. After questioning and going through some examples, I came to understand what he meant to say. The product needed to be tested for validity while it is still in the building stage because it was not completely done. (Which now made sense in development terms– solve the puzzle – test it out and see if you can break it.) But without knowing the aim, the goal, nor the purpose, confusion resulted.

Resolution:

What I did to lessen the confusion was to request a demo and to ask questions.

Request a demo:

Ask to have the product shown to you. This way, the purpose and the objective of the product can be understood.

Ask questions:

Showing seems to be a lot easier than speaking at certain times. But you also need to ask some questions:

• Ask Why they wanted to create this. Knowing why explains the reasoning behind the product. It could have been created out of necessity, or nothing like it exists, or it is a better rework of something that currently exists.
• Ask How the product was made or what it entails to help you see and understand how it works; it’s functionality.
• Ask ‘What if…’- Think of some scenario’s where this product would be used. This verifies that the product will function as it should without any problems.

Leave with more knowledge

To learn more in this meeting, make sure you:

• Communicate as clearly as possible. Apply the ‘KISS’ principle – keep it short, simple.
• Use short sentences when confirming what was mentioned to ensure understanding.
• Ask easy (simple) to answer questions, i.e., yes/no questions to help in clarifying facts.
• Use your imagination to think up of questions – ‘Why did you think of this?’ ‘What made you think of this’? ‘How did this come about?’ ‘Did someone request this or did you see a need for this?’ ‘How did you begin?’ ‘Who else helped?’ There are a gamut of questions to ask.
• Take good notes.
• Leave with a good understanding of the product.

Have you used other methods to get better explanations from other individuals who have a problem explaining what they want or mean? If so, please add to the discussion.