Author: Theresa Pojuner

The Technical Writer is forever growing in status and popularity. They have now emerged as Content Writers, Managers, Web Content Writers, and Web Managers. But the basic ideals and requirements are still the same. They are knowledgeable in their fields (manufacturing, pharmacy, education, development, business, etc.) and they know how to write – clearly and concisely.

As always, communication is the key in this industry; in writing and in speaking. Flexible technical writers will be part of many projects, take ownership of many projects, and will work in an ever changing industry. But within each one, the writer will have to be able to know how to communicate to their audience, whether it’s on the web, through text, or any other media and be able to create and/or follow company guidelines.

How they generate the information is not easy. Depending on their position, they will either have to write as speakers, sellers, instructors, commentators, or even researchers.

• Writing as a speaker means providing information in a more entertaining way instead of text.
• Writing as a seller means providing attributes of a commodity either through marketing, white papers, blogging, etc.
• Writing as a commentator means providing information adjacent video, images, presentations, etc.
• Writing as a researcher means providing specific data information – being able to organize it properly by tags, references, reports, data structures, etc.

No matter which role is taken, the writer has to have a key understanding of what the audience needs and to tailor it to them. They have to be able to be a good listener, focused, and be able to adjust their writing accordingly. They have to be able to manage their time, their team, and be able to continuously concentrate on the outcome and at the same time be able to work collaboratively across all functions.

The above is a general guideline of the new content writer or manager. They still however possess the same basic skills of a technical writer. The most important key is the enjoyment of writing and learning. Without these two attributes, how can you gain the knowledge you need to succeed?

• Enjoying writing means – being able to translate complex or simple material into an easy to understand language.
• Enjoying leaning means – being able to gain knowledge and to understand client needs, architectural data requirements, business processes, the market, data analysis, etc.

But at the end of this is also the satisfaction of being able to share the information.

What do you think of the new Content/Technical writer? They still function the same, and they both still need to have interpersonal skills in order to relate, work, and understand others within an organization. But most importantly, they still have to produce quality documents within a set time schedule.

Planning can mean anticipating, preparing, and being able to predict or forecast possible events. It’s being able to schedule ahead. Some people set up blocks of time for work and availability and move them around to be able to handle situations. But how do you plan ahead for documentation projects?

Here are some suggestions:

• If there are pre-written plans, use them as a starting guide.
• Create a check list to establish what information is needed up front for any document.
• Make sure that your gathered requirements are accurate and valid.
• To maintain control of a project, prepare ahead of time by asking a lot of questions, such as who the SME’s and stakeholders are, and who your target audience is. Identify the types of documents required up front and make sure resources are available for writing and gathering data.
• Set your milestones and make sure you have the right tools available and the budget.
• Make sure you understand the architecture of the system you are documenting; include procedures, methodology, events, actions, etc. This will also help you to build better test plans as well.
• Stay focused and monitor the workload and schedule. If your work load or information load is too heavy, break it down into charts, figures, or diagrams for easier understanding and analysis. If either of them are out of line, then be prepared for unforeseen events to occur.
• Research before a meeting and study previous project timelines in order to provide good estimates of the time needed for your documentation. Also, keep a separate project plan of your own in order to maintain control of the project. You may have items in there that are not mentioned in the overall project plan, such as editing.
• For setting up CMS tools for documentation, make sure that they are not only the right fit for you and the organization, but that they are also user friendly.
• Make sure you have a style guide to follow. This will make the documentation easier for maintaining uniformity in writing, formatting, and styling.
• For security issues, check with your managers and IT personnel and question them about confidentiality, maintenance, issues, protocols, archives, contingency plans, etc.
• Stay organized and begin your documents as soon as you can to stay ahead.

Plan with the future in mind:

• Maintain a directory or chart of all the documents, their content, and associated references. Changes to content that is reused elsewhere should occur across the board, so make sure you note any associated references within a directory.
• Give yourself plenty of extra time within the initial project plan for what-if scenarios, such as sudden client demands or budget and resource changes.
• Make sure that the document is reusable. This is especially important for organizations where modular content is repeatedly reused.
• To ensure the documentation schedule is working well, set up a tracking system and always get some feedback on its status.
• As a final statement, create contingency plans for any unexpected delays and bottlenecks.

How have you planned ahead for your documentation practices?

You have inherited a document that no one is happy with. How do you find out not only what is wrong with it, but also how it should be changed to satisfy everyone? Revising documents require excellent communications skills. You need to also think about:

• What questions should be asked and who should be approached to get your answers?
• Should you just verify the content or should you reorganize and rewrite the content?

How should the writer begin? Finding out what is wrong with the existing document is not an easy task. The best approach recommended is to reach out to others to validate what has to be done. Ask these questions:

• Who is not satisfied with the document and why? –Ask because it could have been written for the wrong audience.
• Who is currently using this document and has copies of it and why? – Ask because they might not have the latest version; verify it.

Next, review the document and gather specific reasons for needed changes. Don’t just find out why it is wrong, find out what was needed or is missing. Then get that information by holding meetings, working across departments, researching and querying all those involved in the original project.

Ask does this document:

• need a rewrite (or reworded) due to a lack of clarity?
• need to be revamped (or overhauled, a real face lift ) due to a lack of organization?
• need to be pitched and revised (corrected) due to its objective not being reached?

If the document needs to be rewritten, find out what is wrong with the verbiage. Ask further questions such as:

• Do they want a briefer, more concise document, or was it too short?
• Was language usage incorrect?
• Was the presentation and the written tone wrong? In other words, was the text too informal or too formal?
• Were the words too technical or not technical enough?
• Did they want more images or less?

If the content needs to be corrected, ask further questions such as:

• Where can you get the correct information? It could just be, for example, that new procedures or policies were put into place and the document just needs to be updated.
• Where are the SME (subject matter experts)? Find all your knowledgeable experts in order to gather all your correct information.
• Why and when were, e.g., policies, procedures, workflows, etc., changed? This way, your readers will see why a revised document was needed.

If the document needs to be revamped, ask all of the above questions as well as:

• In what manner should the document to be altered? Find out exactly how they want it to be changed. If you do not get them to explain what they want, then they will not be happy with your finished product.
• Does it just need reorganization and restructuring or is it all wrong? This is the difficult part, especially if you do not easily see anything wrong with how the document was organized.

If you have had experience in rewriting a document, please share your experience.

Is there such a thing as being able to minimize documentation? There is if you are creating reference sheets or so-called cheat sheets. These are quick reference guides. They are especially useful for referencing material such as scripts, codes, or shortcuts within science, games, writing, etc. They exist for any topic or any field. They will present basic or core information that is relevant to the user. See more about ready reference sheets at: https://staging.management.org/blogs/communications/2011/09/21/what-are-ready-reference-sheets/#sthash.HTLvhQVi.dpuf

Recently, however, I’ve noticed that when the topic of documentation minimization appears, it’s more about reusing documentation so that you end up writing only once. Here are some questions to ask yourself when deciding to reuse content or not.

• Where and when is this piece of information repeated for your stakeholders? (Example: warning sections existing inside user manuals or on detachable user cards.)
• Is this information required in a variety of documentation needed by your stakeholders? (Example: equipment requirements noted within functional, test, analytical, or release documents.)
• What type of information is required by your stakeholders? (Example: detailed business process flows, general facts, quick notes, or illustrated graphics or video data, etc.)

Here are some ideas on how to maintain reused content.

• Separate reusable content into categories. This will also make locating information more quickly. Create a directory or a chart for this listing.
• List content locations. For content fitting into more than one category, list all locations so that updates will be made across the board.
• Rename or create a new content category. For customized content changes, you may need to rename or create a new category. Keeping track of updates is very important. Therefore, make note of the date and time the change was made and make sure all related references are also updated.
• Plan it out. You may plan out your content thinking that the content is valid and accurate, but at the same time, be mindful that last minute changes might occur. If changes have to be made, look at the directory or chart you made and make the change in all associated places.
• Learn from your experiences. If you see a trend, create a style guide for the reuse of content. This will save you time and effort down the line when it comes to not only creating the content, but in also categorizing it.
• Create your spreadsheet. Keep a spreadsheet of all your documents. Include a section for categories if needed, followed by a description of the content, location, the date of the last change, and by whom. It wouldn’t hurt to also add a comment field as well if extra information is needed especially if a particular request was made or if the content is reused in other places.

There are software applications available that can help you keep track of content, paragraph, by paragraph, segment by segment, etc. Explore and find which works best for you if the reuse of content becomes too challenging. But remember to always write for your target audience simply, clearly, accurately, and to the point.

Please leave a comment if you have other suggestions on reusing documentation.

 

Technical Writers wear many hats (traits Interviewer, Researcher, Analyst, Editor, Tester, etc.) and possess many interpersonal qualities. Usually, technical writers have some familiarity with their industry terminology because they either have been educated in the industry, or they have had prior experience in the field. For recent graduates and those in transition, how do you determine if the technical writing field is for you? If you are one of those people, test yourself to see if the technical writing field is for you by answering ‘yes’ to the following questions:

Basic Characteristics

• Do you enjoy writing? – do you enjoy writing about any subject?
• Are you a good listener? – can you understand all that you hear?
• Do you enjoy learning? – are you open to continuously learning any subject?
• Are you a good communicator? – can you get your message across?

Practical Characteristics

• Do you have a sense of curiosity?
• Do you enjoy sharing information with others?
• Are you detail oriented?
• Are you analytical?

Work Characteristics

• Can you work with any type of personality (aggressive, impatient, argumentative, etc.)?
• Are you a team player?
• Are you adaptable to work schedule changes?
• Can you work under pressure?
• Can you handle criticism?
• Do you enjoy performing research?

Personal Characteristics

• Are you organized?
• Are you curious?
• Are you focused?
• Are you reasonable?
• Are you organized?
• Are you accurate?
• Are you persistent?
• Are you logical?
• Are you reasonable?
• Are you patient?
• Are you flexible?
• Are you creative?

Rate your communication skills

• Are your writings providing the right information?
• Are your writings addressing the right audience?
• Are you asking the right questions to get your information?

Writing Exercises

• Can you write a summary of your current functions?
• Can you write a detailed list of your functions?
• Can you create a flowchart of your functions?
• Can you prioritize your functions?
• Can you create a diagram of your functions?
• Are your writings clear, concise, accurate?
• Can you write a set of rules for yourself for, e.g., studying?
• Create a bullet list of the above rules.
• Create a table for the rules.
• Create a diagram and flowchart of the process for studying.

Technical writing is a challenging field, but a very enjoyable one if you are passionate about it. You are not just writing. You are conveying important information that everyone within an organization needs in order to maintain productivity. You will become the knowledge manager of your organizations information. It is a coveted and a very important position and is highly regarded in many organizations from pharmaceutical to manufacturing, from any technical to any educational field. Technical writers can be found working within any industry, e.g., software, manufacturing, financial, automobile, pharmaceutical, publishing company, etc.

The skills for a successful technical writing career are similar to those for success in any career. Be focused, logical, organized, creative, and know the product. And one more important note. Use your interpersonal skills to gather your information and to work well with your clients, users, or SMEs (subject matter experts). Doing so will make you a successful technical writer.

Making relevant information stand out and noticeable is important for various types of documentation (including presentations) within any type of industry from pharmaceutical to manufacturing to training and marketing material. Designing skills are just as important as writing in creating documents. We want to interest the reader and not have them fall asleep. Common types of highlighting involve font styles and sizes, shades of coloring, underscoring, shadowing, etc. but there are also other ways such as the ones mentioned below.

Boxes

• Separate out information, fact, figures, references or any important data within a box for better comprehension.
• Apply a shade of color within the box.
• Italicize or bold pertinent information.

Charts

• When there is too much information, break it down into charts, figures, diagrams for easier understanding, analysis, and to assist in explanations. For example, for a business process, create the business diagram and then break it down to a more logical detailed explanation or functionality.
• Add in grid lines to separate columnar or grid information.
• Apply a shade of color to highlight, e.g., headings horizontally or vertically.
• Color in some boxes, circles, various shapes when using flow charts to follow certain business process flows.
• Use hierarchies, matrices, pyramids, or cycle diagrams to highlight relationships.
• Use arrows, lines, callouts, unique charts that highlight specific data.

Formatting

• Highlight your creative succinct titles or headings to indicate what the information is about.
• Use short sentences to describe or detail data.
• Apply spaces between paragraphs and bulleted points.
• Apply more white space.

Other Ideas

Also helpful is the use of the following: caricatures, pictures shapes, icons to aid in descriptions (especially comical ones), and where applicable, include music or make them interactive. In addition, embed videos, links, screenshots, etc.

Grammar

• Use your best writing skills.
• Design for the audience; use the active voice in your grammar and not the passive voice to get the information across to others.
• Build sentences that are short, succinct, and precise for easier readability.
• Most importantly, make sure the audience understands your terminology.

So when creating documents involving anything from requirements to functional to test cases, to installation instructions, technical instructions, release notes, online help text, etc., remain organized and remember to ensure the look and feel of the document is appealing and useable. This is especially true when documentation projects are extremely complex such as in communicating process flows or complex applications.

Another important reminder, is to make sure that the document is reusable especially for fast moving organizations where there are constant revisions or if a certain modular coding is applied repeatedly within various applications or products. As an example, review several test plan documents to view examples of certain scenarios being reused under various situations.

Hopefully a style guide exists within the company to aid in the application or styles for various documents. If one does not exist, create one. This will ease the burden of future documents. This is especially true if the organization is global.

Please leave a comment if you have other suggestions for highlighting text.

 

 

User manuals provide a road map for the user. Many technical writers embed screen shots or images into documents to aid the user in seeing what a product or application is composed of, how a task is achieved, and most importantly, what not to do. But there are always questions as to where and how many images should be embedded, should the image take up a full or half a page, plus where should the placement of text be set for the image; adjacent, above, below, etc. Is there another solution?

Technical writers or communicators should always try to find a simpler way to display how one can navigate from one area to another or how to define or describe systems, applications, and products. Many new solutions or products have evolved now where we can just develop slide shows to display, describe, and to project what has to be done, can be done, and what cannot be done visually. They use it for marketing, education, enhancing their product, sharing of knowledge, etc. Many of these new platforms are now cloud-based and provide good security and file sharing.

Once slides are created, individuals just need to select the desired file, and at their own pace, just click the appropriate option to move from one screen shot to the next for viewing. Slide shows are easy, convenient and entertaining. Many organizations now create various tutorials with cleverly designed characters to help describe what the object of the presentations are about.

Creators can now animate the characters depicting faces with different emotions (depending on the situation of the event). We are part of a generation where we can use the right side of the brain for displaying our artistic skills and enjoy the outcomes of creative designs for wire framing, mapping, storyboarding, etc.

These slide shows or presentations make it easy for us to socially communicate, share knowledge, and collaborate on the web or through any popular medium. Even children at the age of 2 know how to touch an icon on a tablet or screen and know that by doing so, their favorite video will appear. I know this for a fact because my little nephew can do it.

Slide shows cannot completely take the place of user manuals, but they are a great option that is now available for us to use. Presentations cannot be created any easier than they are today. We can apply animation, audio, and visual to convey our documentation, tutorials, and anything else that has to be communicated. We also get to have fun while creating it for our audience.

Fun is mentioned because it is holiday time and close to the end of the year and I’m smiling because I’m happy that we have such wonderful readers of our website. It’s time to say Thank You all for being our readers this past year and for sharing your thoughts with us. Have a Wonderful Holiday and a Happy New Year. Happy reading in 2014.

Communicating the definition of architecting or ‘to architecture’ can be defined in software and technically as what is to be set up. It is the building of a configuration or an arrangement of objects; a structure.

In the software/ technical world, designing and documenting the architecture of a system is composed of planning, describing, and displaying the different relationships of various items making up the system. In other words, the architecture of any system is broken down into its components and shows how all the pieces are associated, connected, or joined (as in data modeling). In documenting the system, it is not only detailing the make-up of the system, but also includes procedures, methodology, events, actions, etc.

Many skills are required to produce an effective and valuable functional architecture. When we build an architecture, we need:

• to collaborate among our coworkers,
• have great communication skills, and
• most importantly, be organized.

Without these skills, informative technical and requirement specifications, business assessments, review processes, etc. cannot be completed for the architecture.

Also, guidelines need to be set before an architecture can be built. Building an architecture (even of a document) is not easy. We can think of a pyramid or a hierarchy. In so doing, do we work from the top down or the bottom up? Do we start at the top and know what you want to end up with or do you start from the bottom up and know what you have and try to build what you want from what currently exists? It is a difficult choice and each organization has to make up its own mind and decide on what fits them best.

To help the decision process along the way, and to, e.g., help the technical writer build on the architecture of a document, here are some questions in random order:

• What is to be the end result
• What ideas, resources, etc. do you have to get to the end
• Whom can you rely on for support
• Do you have the knowledge and skills to perform the task
• Do you have the tools to create the document
• Whom can you get details from
• Whom are you writing for
• How is the document to be organized
• Where is your information located
• Is cost a major factor
• What are the future plans

Think about how you will begin the document. To help, try to number the items above by priority and see what works best for the organization. Only then will you know if you will be working from the top down or bottom up. As noted, the above example can also be applied when designing an architecture of a system. There are many more questions that need to be answered. The above is just a beginning.

How would you define architecting and what experiences and solutions have you had in architecting a, e.g., document?

Use cases and workflow diagrams are two essential practices or methodologies that will effectively demonstrate a functionality of a product. To understand their value, they have to be defined.

Use cases are a way to show how a user, consumer, or customer can utilize, or operate a product or application.

• It systematically details the reason for the application; how it works to achieve the end result.
• It is not a step-by-step or itemized listing of how to accomplish a task. Use cases have to be able to answer questions such as what are the tasks that have to be done and how deep into a program does the user have to go to accomplish the task.
• Use cases are great for helping users work through an application.

Workflow diagrams on the other hand will display, model, or diagram a whole picture of a product or application process.

• It can show you step-by-step how to accomplish a task. It is an image of what the product or application does as it works toward an end result.
• It is like a road map showing you where you will end up if you take a particular route. These workflow diagrams can visually show the functionality of an application in an appealing manner. They are easier to see and understand, and are more entertaining visually than reading.
• On an even higher scale, you can use or prototype a particular workflow diagram as a business model. The workflow diagram answers questions such as what is the scope, range, or possibilities of the application or product and what are the ‘what if’ scenarios.
• Workflow diagrams are great for training and capturing the essential functions of an application or product.

Conclusion

Use cases are critical for completing tasks or having users work with an application or learning a process. But when detailing an application or process, workflows are better for showing their behavior.

Technical writers need to be able to distinguish the two methodologies and to know when to apply them. They need to be able to channel and harness their knowledge to create all of the above. There will be situations when both methodologies have to be applied to accomplish a task. For example, if the steps to complete a task are lengthy, then sometimes it is much better to give a good overview by first creating a use case for an example, then a workflow diagram and then maybe also include a flow chart as well listing very detailed steps that are involved. These types of situations show why it is important and valuable to know how to use the two forms of communication and to see the benefits of both methodologies.

If you have had to design use cases or workflow diagrams, what has been your experience? Is one better than another?

Curating content is defined as selecting, organizing, and presenting content, mostly for online use, either for searching or marketing, or actually any form of business or profession. How do you curate and communicate your content? How do you provide information smoothly and quickly?
First you have to select it, then organize it and make it presentable. It has to be valuable, accurate, and searchable. As with writing the content, you need to:

• Know the target audience.
• Ensure that the content is reusable and relevant.
• And depending on the system being developed, note if the content is to be classified or confidential and design accordingly.

To get started:

• Locate templates and models to give you some ideas as to how the architecture of the content should be established; getting started to build a system is not an easy task.
• Group and categorize the content (e.g., by project or types of documents or by videos, diagrams, etc.) for easy access. Organizing them is not the only key to having a good searchable structure or system. Know what you want your system to present, to be able to do or to provide.
• The content also has to be formatted in such a way as to be visually presentable and easy to use. Getting the right look and feel of the system will not only make it more appealing, but more useable as well.
• Find where existing content is being stored and then decide on not only the (possibly) new location (cloud, database, etc.) of the system, but how content will now be stored and also who will be in charge of the content and the processes involved in creating and maintaining the system.
• Again as always, if this is a global company, translation processes need to also be considered.

To ensure that the content is valuable, visualize a user needing access to the content. Develop some scenarios and make sure the framework is suitable for the user. You can also mail out a survey or questionnaire and gather needed information. You might want to say you are setting up a test case. Find out what users want in the searchable system. Once you have a prototype, have users try it out and see where adjustments need to be made.

Also, note the costs that need to be considered in maintaining the content. The above are only a few of the many things that have to be considered. There are resources and packages available that can be of assistance, but you need to know what you want and need for curating content.

Don’t forget that once a system is established, plan ahead and create contingent plans for any unexpected delays and bottlenecks, and ensure that all problems can and will be resolved. To ensure the system is working well, set up a tracking system and always get some feedback to its functionality.

If you have are involved with curating content, please leave a comment as to what has to be considered before developing a curated system and your experiences.