Author: Theresa Pojuner

With social media connecting us to more people globally, technical writing was sure to follow the same path. What does it take to be a global technical writer? How much the global clients need and what they need has to be clearly defined. The key will be in understanding the local culture and language. But how will this interpretation and translation of terms be understood if you are not there? Think of this as providing e-training and you are providing a distance learning program – it might help you in figuring out new ways to get your information across. But here are some ideas to think about.

In terms of writing:

• Create a standardized dictionary of terms (including terms to avoid) and spelling (remembering spellings such as ‘color’ vs ‘colour’).
• Be flexible in adjusting your use of words depending on whom you’re writing for. One culture may like explicit detailed longer explanations, whereas another may like short succinct definitions. As with many target audiences, another culture may prefer illustrations instead of words, or both, or videos or webinars instead.
• Plan out your documents and create outlines for approval.
• Determine ahead of time how you will be managing changes or updates.
• Give appropriate examples within explanations; make it pertinent to the product or application. Do not use examples that the client’s culture may not understand.
• Get your first draft authorized to ensure you are writing the way you are supposed to be and are relaying the correct information using the correct terms. It is better to find out the problem areas up front than have bottlenecks later on and be late on delivery

In terms of managing:

• Make sure you have all the information you need before you begin writing.
• Prepare questions ahead of time for meetings to ensure there’s no misunderstanding before you begin producing your document.
• Make sure the same tools or technology is being used for sending and receiving information. It would be a waste of time if you wrote, illustrated, created videos or used other means to transfer knowledge in one particular format and the client didn’t have those applications.
• Have open lines of communication to ensure knowledge and comprehension is correctly conveyed
• Make sure that deadlines and milestones are understood by all parties- hold intermittent status meetings to ensure that everyone is still on the same page and that the project is progressing as it should.
• Be flexible with time schedules depending on whom you’re meeting with.
• Be sure to answer the question ‘how to handle security of the document’ if that is an issue.
• Invest in a document managing system if the need arises to maintain organization.

As a gobal technical writer, you have to envision or put yourself in the place of the stakeholders. There will be a lot of translation hindrances or obstacles, but being vigilant about maintaining direct communication will decrease the number of error and barriers.

If you have had experience being a global technical writer, please share your experience.

The cloud (virtual software service) and mobile devices are now being used more and more as a means to provide users easier access to documentation and training. What does that mean for Technical Writers? It means more opportunities, work, imagination, and knowledge,

More opportunities will exist for the Technical Writer to become involved in working with the latest authoring tools and applications to create the written material (from requirements, specifications, compliance, training, marketing material, etc.), the latest mediums (mobile devices, i.e., tablets and smart phones) used to display the work, and the latest service technology (the cloud). The Technical Writer‘s passion for learning will be quenched in this area..

More work will exist for the Technical Writer, because many corporations, public and private, now want to place their documents on the cloud, but in what fashion and how will they all be managed, organized, tracked, and remain secure, which documents should be cloud based for archiving and which ones should not (i.e., sensitive matter), and which ones need to be easily accessed? Will training and marketing material and proposals go onto the cloud for easier accessibility, but not specifications? To answer this, the Technical Writer will have to interview all stakeholders up front before creating any documents for the cloud or mobile devices.

More imagination will be needed by the Technical Writer to organize, categorize, and manage the material in such a way that the users can access what they want and need efficiently. Should an application be created up front so that the user can easily view what he is searching for and then present all related documents, or should they be listed within simple folders by project or both or should the company invest in new applications such as content management systems? Throughout the process, the Technical Writer as a visual and user experience designer has to ensure ease of navigation and graphically friendly interfaces to provide what the user wants and needs.

More knowledge will be required by the Technical Writer to grasp the new technology, and to also remember the requirements of the organization and its stakeholders. The Technical Writer will need to understand the technology’s capabilities, understand how it fits within the business structure (and system architecture) of the company, and be able to convey it to others, especially when writing Request For Proposals. This is emphasized because without this knowledge, the writer will not be able to document nor communicate the business reasoning, process, scope, nor desired outcome of the project.

Throughout this whole process, consistency and order must be maintained. One of the attributes of being a good Technical Writer is that of maintaining consistency and accuracy. To accomplish this, the Technical Writer will need to perform functions as an analyst and a project manager in order to keep the goal in sight. This will not be an easy task, but if done in small steps, is achievable.

If you are currently employed:

• begin to write even if it is about a simple process or procedure that you perform daily.
• write about your job and what the requirements are for that position.
• write about all your daily tasks and how long it takes to perform the job.

This is a good way to see if you really would like to become a Technical Writer because when you begin to write about your functions, you might see that it is not an easy task.

To improve your skills, take classes to develop or improve:

• your writing and grammar skills, as documents have to be clear, precise, and error-free.
• your communication skills for not only conveying instructions within documents, but for also improving your understanding and listening skills.

To search out writing opportunities, you could:

• begin by reviewing a list of potential jobs and their requirements. Find and focus on those companies that interest you and see what types of documents they produce, review their style of writing, and see if you can be of help to them. Also, consider other writing opportunities and see if you can begin to work as an intern.
• look into communication as well as presentation positions as these also involve a lot of writing. From that experience, you can then call yourself a Technical Communicator. Also look into analysis, coordinator, translator, and training positions as they all involve communication and writing skills.
• also look into freelancing positions to make sure you would enjoy being a Technical Writer. These positions are good to work in because you will experience what it is like to have to stick to set deadlines and simultaneously be flexible enough to adjust to changing requirements. In other words, it will show you how adaptable you are
• become a Subject Matter Expert (SME) in a particular field by taking classes for any technical skills that really interest you, and write about it
• start off in a writing group to meet others and network. With today’s social media advantages, join groups on and off line and communicate\meet up with others.

The skills for a successful technical writing career are similar to those for success in any career. Be focused, logical, organized creative, persistent, know the product, and apply the new platinum rule ‘treat others the way they would like to be treated’. If you do not get along with your clients, users, or SMEs then you won’t be successful. Make sure you understand each other and that you are all on the same page especially when beginning a new project.

The Visual Communicator/Designer is involved in the page layout, the framework, the elements on a page; it is never ending for a Visual Communicator. Creativity is everything for a Visual Communicator. As a Technical Writer, you also have to be a visual designer. You need to be up on all the popular tool sets as well as be aware of the more popular methods of presentation. Let me elaborate on that. Popular methods of presentation include webinars, blogs, mobile, classroom, meetings, storyboards, and online lecturing. Presentations are relevant for delivering information to the target audience and to keep them interested, you have to be prepared with dynamic deliverables.

It is a good idea to have viewed a lot of presentations yourself to see what is liked or disliked. Presentations can’t just be graphs and its components. It has to be visually appealing to maintain the audience’s attention. It has to show relationships between all the different elements on a screen or page.

Images

Use illustrations, tables, charts, graphics, and even print screens; let the image do the describing and make sure you note any exceptions to any process. For images that also involve text, separate the graph from the text. Keep the audience’s attention, for example, by not just presenting a graph or chart; add in light bulbs, colorful fonts, or other images or patterns to highlight certain key points or areas

Humor

Whether it is process that you are presenting or a new product, it is a good idea to include a little bit humor or cartoon to break up the material or else the audience will be on information overload. Have the cartoon do the pointing for you. They need this humor to digest it all.

Text

For a presentation that might involve a lot of text, use bullet points and make it simple; less verbiage. Also, use icons, numbers, and/or alphabetize. Include flow diagrams when moving from one point to another instead of verbiage.

White Space

To reemphasize, make it visually appealing, logical, organized and helpful by separating out data or material. In other words, use a lot of white space. The simpler the design, the better.

Mobile Devices

With mobile devices being so popular, once you create your visual design, test them out on certain mobile devices to see how they appear. You may need to make adjustments so that images will not be cropped or cut off.

As with technical writing, visual designs have to be clear, concise, organized, and provide what your target audience requires.

Lots of questions have been asked as to whether or not you need formal training to be a Technical Writer. Personally, I feel the answer is yes. You need to have some kind of training or degree, whether it is a degree in journalism or a certificate in Business Writing, or a degree in English or Communication. But it is even more than that. Today’s Technical Writer needs a technical degree or a technical background to get a foot in the door, such as a degree in the Sciences, i.e., Biology, Computer Science, Engineering, etc. Many companies have hired people who are not technical and are just writers and have been disappointed in the results. Reason being, their responsibilities included:

• Gathering requirements from subject matter experts such as clients, developers, etc.
• Translating complex technical information, development and relational database concepts into clear easy to understand language for developers and users as well as for training and marketing material
• Understanding complex technical information and organizing it into logical sections that can be followed by the target audience
• Creating a variety of documents that involve standard operating procedures, request for proposals as well as usability testing and regulatory compliance requirements
• Having good communication skills and being able to stick to schedules
• Developing project plans and being a knowledge liaison across departments.

Originally, people started off with a degree in writing (i.e., journalism, Business Writing, English) and worked in various companies or did freelance work. Sometimes this work took them into the technical writing arena. From there, they gained more and more experience within the technical field.

If you begin with a technical degree, you can end up writing for an infinite variety of industries from financial to education, to technical companies to publishing, to Civilian and Defense industries to government contracts, to any kind of global contract. If you begin with a degree in the sciences like Biology, you can possibly end up working in pharmaceutical companies or in a related field. Also, fields such as engineering, chemistry, physics, aerospace, manufacturing, computing, finance, consumer electronics, and biotechnology all need Technical Writers. The field is wide open to you.

So yes, you need some sort of training to be a Technical Writer, because a Technical Writer has to comprehend technology in a way that can be explained to a target audience. You have to be able to research and understand the technology you are working in. Think of the position as a Technical Communicator, because we are translators and professional editors. We are translators because we break down technical terminology into understandable everyday usage for our target audience. We are editors, because our documentation has to be error free in the usage of grammar, spelling, etc. This is especially important when producing writing matter such as marketing, training, or compliance material, which reflects upon a company’s image.

Do you agree?

When problems are encountered during the testing phase of a product or application, they have to be noted so that the problem can be corrected or prevented before the next testing phase. These problems have to be noted within a form known as a List of Errors form or a Problem and Resolution form or an Incident form. For us right now, we’ll simply call it a Bug List. Any irregularities or anomalies noted within the Bug List will be passed to the development group, who will resolve the problem.

The Bug List should contain at least 5 columns. The column headings should be listed accordingly: ‘Date Bug Found’, ‘Description of Bug, ‘Resolution’, ‘Date Bug Closed ‘, and ‘Comments’. The tester will describe in extreme detail the exact steps that led up to the occurrence within the ‘Description of Bug ‘column. This part of the form is crucial for replicating an error. Without it, the developer will not be able to duplicate the error and hence correct it.

For finding bugs (problems), every test plan has to be extremely detailed and every test scenario listed. Yes, there will be times when not every case/scenario is noted. If the tester does create a unique case, this case should be noted within the bug list. This way, when the application/product goes into the next testing phase, this new test case will be added to the test plan, as well as tested.

When testing is completed, the list will be directed to the appropriate developer and Project manager involved. Every bug found should be corrected, but then there are various grades of bugs. There are quick fixes, such as spelling errors, simple fixes which involve minor programming, i.e., a value was to be added and wasn’t, medium sized fixes which take a few hours when a functionally will not work under certain conditions, serious ones which require rework, and red flag ones where the applications/product seizes to work. Depending on time constraints, the more serious ones (red) will be corrected first. Then when time allows the minor ones will finally be corrected.

Once the problem is corrected by the developer and the fix is inserted into the ‘Resolution’ column, the tester will be informed. The tester will then perform regression testing where the tester tries to recreate the error. Once the tester is satisfied that the issue is resolved, a date for closing the bug can be inserted within the ‘Date bug closed’ column, and any pertinent comments needed can be added to the ‘Comments’ column.

For more complicated testing, there are now programs that will perform automatic testing when needed for direct testing and for regression testing. These new applications are really helpful especially when repeated tests need to be done. To help you keep track of all the bugs, there are also programs out there now that will assist you in keeping track of all bugs. These tracking programs are very useful, especially when a Quality Assurance Manager needs to be on top of all Red flagged issues.

This part of the Testing phase, where time is spent on creating the Bug list, has to be taken into consideration when scheduling time within the project plan. The same goes for adding in time for correcting problems and regression testing. Without the project plan, we would not be aware of our time line or different events that have to occur from a product or applications initiation or start to its completion. But to get back to the Bug list, without it, we would not be able to communicate and keep track of all these problematic issues that need to be resolved.

Once the application/product has been created and before it goes live, a detailed quality check will be conducted. To perform this check and to ensure that all functionality/features/ attributes/ facets of the product perform as intended, a Test Plan is created and used to perform a detailed check on the application/product. A test plan can be created for prototypes, system and data migrations, system designs etc, but what will be posted here is a sample test plan for a simple field within a product. No matter what type of test plan is created, the logic and organization of the test plan created will be similar to what is noted.

To clarify the definition, Test Plans are needed to help the Quality Assurance (QA) tester conduct a series of tests in order to validate an application via functionality, task oriented or even mathematical or data tests.

To present the Test Plan, use an outline format so that a task can be noted and insert sub-tasks to further define the test. This format seems to be the easiest to follow, as Test plans are usually extremely detailed. As a simple example, if a numerical field is to be tested within an entry form, list this as a task. Then below it, list sub-items that need to be checked.

For example:

• does the field accept the maximum length of numbers,
• If more than the maximum length of characters is input:
  • does the field accept it,
  • does an error message occur; if yes, note in bug list
  • does it accept alpha or extraneous characters; if yes, note in bug list
  • does it accept decimals.
• is the data saved when you go to the next screen and return (check previous screen as well)
• check the database
  • is the data saved as entered.

All this may seem tedious, but those are the typse of scenarios that need to be tested. Every situation listed has to be tested step-by-step and verified. Every action that a user might perform has to be noted and checked. Along with verification, the test plan should also check to see if the application is logical or if the flow makes sense. The creator of the test plan needs to have placed them self in the mindset of the user and include different actions that a user might perform.

The beginning of the Test Plan, along with pertinent instructions, should include:

• System requirements denoting the platform under which the program would and/or would not work, who can access the program, and what results should be expected. This precedent should also be verified.
• A set of detailed systematic instructions as to how the application should work and what steps the tester can undertake to validate the authenticity of the program or to invalidate it. In other words, the tester needs to see if the program can be broken or fail or has faults in it; to invalidate it.

Test plans are lengthy, detailed, and have to be part of the team’s project plan. Test plans must consist of a series of test cases or scenarios which will aid in retracing steps whenever problems occur as well as for regression testing.

When problems are encountered, different resolutions should be tried and then listed. If no resolutions are listed, note them as irregularities or anomalies within a Bug List.

We will talk about a Bug List in the next post.

I am seeing a trend here, where TW=BA=UX. Multitalented Technical Writers are now becoming more involved within organizations. They must know the business as well as a Business Analysts, and they are also becoming our Usability Experts. They are a versatile, adaptable, resourceful group of writers, mainly because their function is in knowledge transfer. They have become so involved in the business processes that they are now our Knowledge Managers with sub-titles of Technical Writer, Business Analyst, and Usability Expert

Let’s first define a Technical Writer (TW), a Business Analyst (BA), and a Usability Expert (UX). Checkout this comparison chart:

Tasks required	TW	BA	UX
Understand the business	Writes about business models	Analyses the business model	Uses business models
Transfer knowledge	Ability to communicate	Ability to communicate	Ability to communicate
Work across various functions/disciplines	Gathers information	Gathers information	Gathers information
Information Architect	Designs a user interface (UI) structure	Designs a interface (UI) structure	Designs a user interface (UI) structure
Governance of information	Handles data or information	Handles data or information	Presentation of data or information

The TW translates the business terms and technical information into simple easy to understand terms and guidelines so that the project can be accomplished.

The BA translates business policies, strategies, or regulations into system requirements for a project and takes a course of action to ensure the completion of the project.

The UX translates business requirements into information retrieval by ensuring the right data is captured or presented through an defined process.

All three roles have to:

• Analyze and document the current business processes to ensure that the content is understood by the project stakeholders.
• Create and present process flows, information architecture, site maps and prototypes for complex applications.
• Identify and document future business processes including opportunities for process improvements.
• Understand the features, functions, and capabilities of applications or services or products in order to achieve high performance goals.
• Gather business requirements using different requirements gathering techniques (e.g. interviews, surveys, meetings, etc.).
• Analyze and document business requirements using specific modeling or case tools.
• Partake in tracking changes to the project.
• Work with the business stakeholders, i.e., graphic designers, web developers, business analysts and software engineers.
• Translate business requirements into technical and functional specifications.
• Collaborate with the technical resources or any subject matter expert to gather specific (data or design) information.
• Conduct, coordinate, and perform user acceptance tests, user walk-through sessions, and other ways to test the designs as well as create test plans to ensure adherence to specifications.
• Act as a liaison between the IT project team and the business stakeholders.
• Translating client goals into user-centered designs.
• Write user-friendly text for on-screen instructions, headings, button labels, link text and other matter that have an effect on a user’s experience .
• Create guidelines and sharing best practices.​

The role of the technical writer is ever evolving and becoming more relevant every day.

I’ve come up with the following tips to follow when creating a document. You can think of it as a checklist. Hope you find it helpful.

• Know your SME (Subject Matter Expert) – find them and collaborate; create relationships and work with them and inform them of why you’re there; use any opportunity to gather information. Help them help you-assist them by preparing questions and information that you already know and find out what is relevant. Ask what (is the product or its features, etc.), why (is it done this way, was it created, etc.), where (does this take place or belong, etc.), when (does or did this occur, etc.), how (is a process or procedure done, etc.) and who (is affected or is involved, etc.).
• Know your target audience and their preferences – share and connect; find out what they want and need and in what format, be it video, print matter, charts, or training sessions. Show examples of previous documents to find out what they prefer.
• Make sure your stakeholders are all in sync before any material is created; else you will be rewriting and rewriting.
• Be concise and get to the point, make it simple – less verbiage, No more than 5 sentences per paragraph; use outlines, create quick reference guides and style guides for easy referral.
• Use illustrations, tables, charts, graphics, print screens – let the image do the describing and make sure you note any exceptions to any process. Use icons, bullets, numbers and alphabetize – make it visually appealing and be organized and helpful by separating out data or material.
• More white space – have plenty of white space- great for notes and readability.
• Check your grammar and spelling – get the words right; correct and simple and know your terminology.
• Know your timeline, workload, and prioritize – don’t be late; be organized and ready. Know your goals and schedule deliverables accordingly.
• Get it verified and authorized – make it good to go.
• Create your style guide and check list – list necessities or requirements, and maintain consistency and standardization.
• Listen and learn, be open – be knowledgeable and collaborate.
• Your words are your voice – be a trainer through written material. You are the editor, illustrator, and designer of your information. But most importantly, you translate information in a clear and easy to understand language to your target audience.
• You are the knowledge manager – the gatekeeper; make sure you track and organize your documents.

If you have other tips to share, please leave a comment.

A company should always have a process in place whenever changes occur. This should be noted in a department Style Guide as a process. If it already exists, make sure that document revisions are part of the change process and that all necessary people are notified of changes. The change process will ensure that the process of updating the document is completed smoothly and without any consequences. The reason behind the update, the result desired, and the accuracy of the change has to be documented and distributed to all involved.

Updates

As an example, when an application request comes in and an application has to be modified, the reason behind the request as well as how it changed and who was involved has to be noted before any steps are taken. From the onset, to ensure a smooth transition, the appropriate people should be notified as soon as word of a possible change might occur. This will provide ample time for the technical writer and project planner to prepare for the updates. The writer can pull the necessary, essential, or any related documentation that will be affected and the planner can add the project to his schedule with adequate resources. Note: This is why a list of documents, their location, related projects, dates and last updated date should always be noted for the technical writer, researcher, and developer.

Organization

Organize or categorize documents on a list (i.e., a spreadsheet or a table) according to what is most suitable for the organization or for you. If images or graphics are involved, these should also be located in one folder and then broken down by project with sub folders if needed. Add links to these images, figures, or graphics within your table. This way, they can be easily located and retrieved, and have appropriate updates completed.

Check List

For each of the updates, validate them using a check list that was created to ensure that all relevant information was noted and modified with accuracy. It is a good idea to also include the following categories to the checklist along with any sub items: notifications, tests, approvals, projects, locations, users, etc. We want to be absolutely sure we did not omit anything.

To maintain documentation accuracy, remember to always get it verified upon completion and signed off. If you have additional tips, please leave a comment.