I just finished the CSU series of webinars on Teaching and Thinking with AI, led by José Antonio Bowen. These included A.I. Literacy & Prompt Engineering, A.I. Grading, Detection, and Policies, and A.I. Assignments and Assessments. It was an amazing series on using AI in the classroom to help students think differently as well as great tips for usage in training in the real world. My big takeaway is that AI (generative AI) won’t be replacing us anytime soon, it has a ton of flaws returning incorrect information (fake references – so always check your references), and requires plenty of time to get prompts to return a modicum of usable results. One example I am experiencing is that I am getting contacted by recruiters on a popular job site for jobs I don’t do. The jobs are so far off of what I do that at first I assumed it was a mistake until I realized, after the webinar series, that whatever AI they are using isn’t providing reliable results. The prompts they are writing must be off.
However, it really got me to think differently about communication. Every bit of communication needs to be in a prompt that is submitted into AI if you want to be able to use or be inspired by your use of AI. If you want a specific tone, mood, specific time frame etc. – state it. So refine your prompt over and over until the results are better.
There are a variety of tools that will cost you per month for premium results and each has strong points and weak points. So, really getting to know your AI tool, like any other tool, and taking it’s results with a bit of skepticism can help. Don’t be afraid to keep tweaking your prompts until you get the desired results. AI is here to stay so keep practice learning how to use it. Learning it and being able to use it in business, training, and education will be a valuable future-skill.
Some current existing AI tools (this is not a full list just some I found interesting but not necessarily had tried yet).
Claude.aiThere is also a smaller Haiku and a larger Opus.
ChatGPTIf you have only used the free version before May you have been using GPT 3.5
CopilotMicrosoft owns half of OpenAI so CoPilot (is really another version of ChatGPT as far as I can tell)
WolframAlpha combines the computational powers of Wolfram|Alpha with ChatGPT
Piis focused on dialogue and role-playing and has a good voice interface
Poe and ChatHub provide access to multiple AI through one interface
There are additional open source models such as Meta AI, Huggingface, Llama 3, etc. Other resources include APIs, chatbots, study assistants, browser extensions, agents, voice, dialog, etc.
Imagery
Image Creator from Microsoft Designer (free access to Dalle3)
Do you want to become a writer or improve your writing for your job? The Advanced Technical Writing/Communication course starts soon at California State University Dominguez Hills. The course is entirely online and students learn advanced technical writing techniques along with improving their writing skills. Students get hands-on experience creating portfolio pieces they will need to apply for job positions. As we discuss key areas of technical communication, we work on putting together a portfolio so you can show what you know right away.
Students may take the Advanced Class even if they have not completed the Intro course as long as they have some writing experience. The certificate at California State University Dominguez Hills consists of three courses. Check out more here. The entire program for the certificate is taught online (and will continue to be taught online). Find out more information on the CSUDH Technical Writing Program website. Dr. Kondor teaches the Advanced course and the Information Design course. Check out the FAQ on this site if you have questions.
The Advanced Technical Communication course starts on October 21st, 2024. For questions, email learn@csudh.edu or call 310-243-2075. To register for courses, call 310-243-3741 (option 1) or go online. You must complete all courses in the technical writing certificate program to receive the certificate.
Lu Kondor has worked as a technical writer for more than 20 years at major corporations. She has a Doctorate in Business Management and has created a large variety of documents, videos, and copy for organizations in entertainment, software, public utilities, manufacturing, oil and gas, chemical, B2B, consumer-based products, and the nuclear process industries. She is an adjunct lecturer in Advanced Technical Writing as well as Information Design for more than 17 years.
I teach the Advanced Technical Writing/Communication course and it starts soon at California State University Dominguez Hills. The course is entirely online and students learn advanced technical writing techniques along with improving their writing skills. Students get hands-on experience creating portfolio pieces they will need to apply for job positions. As we discuss key areas of technical communication, we work on putting together a portfolio so you can show what you know right away. Students may take the Advanced Class even if they have not completed the Fundamentals course as long as they have some writing experience. The certificate at California State University Dominguez Hills consists of three courses.
Lu Kondor has worked as a technical writer for more than 20 years at major corporations. She has a Doctorate in Business Management and has created a large variety of documents, videos, and copy for organizations in entertainment, software, public utilities, manufacturing, oil and gas, chemical, B2B, consumer-based products, and the nuclear process industries. She is an adjunct lecturer in Advanced Technical Writing as well as Information Design for more than 17 years.
This is a common question I’m asked by students. Active voice is a sentence with an action verb where the subject of the sentence performs the action expressed by the verb. Active voice is clear and concise and active voice sentences are less wordy. To understand active voice, we need to think about passive voice.
In passive voice, the subject receives the action expressed by the verb. For example, the man was bitten by the dog. The dog is acting upon the sentence subject (the man) meaning it uses the passive voice. What would be the active counterpart to this sentence? The dog bit the man. In this active voice sentence, the subject (dog) performs the action (bit) to the individual being acted upon (man).
Examine the passive and the active sentences in Figures 1 and 2. The wordiness of the passive sentence is noticeable (21 words vs. 19 for the active sentence). Most readers of technical documents read quickly, skimming over the material or scanning it to find exactly what they need. Longer sentences are more difficult to skim and scan. When a document user repeatedly rereads a technical document to understand its meaning, they will skip sections or potentially infer the wrong meaning. The result can lead to a negative and potentially dangerous misinterpretation of the information.
If you struggle with identifying passive voice, there are some quick tricks to look for passive voice. First, identify the subject of the sentence. Once you know the subject, determine if it is passive by asking yourself is the subject performing the action (of the verb)? Or is the subject the recipient of a verb’s action?
Are you looking for another way to recognize passive? Look for forms of to be (see figure 3). Check out this passive example: Action on the bill is being considered by the committee. A big clue in this sentence is the phrase is being.
Examine the passive example – Large chunks of asbestos-laden material will be removed from the facility on the second and third floors by asbestos abatement teams. The use of will be is a clue to look at that sentence further.
There are instances where a tech writer may want to use passive voice. Use passive voice with care to be sure the writing is clear and concise. Try the following exercise. Find passive examples online. Then consider the answers to the following questions:
Did you understand what was said, or were things vague?
Was the use of passive voice understandable?
Should the writer reword the example(s)?
If you decide to use passive, test the document with several users to be sure your writing is clear, concise, and not misinterpreted. But remember, you should have a good reason for using passive voice in your writing.
Lu Kondor has worked as a technical writer for more than 20 years for major corporations. She has a Doctorate in Business Management and has worked in a large variety of organizations including entertainment, software, electric utility, manufacturing, oil and gas, chemical, and nuclear process industries. She is an adjunct lecturer in Advanced Technical Writing as well as Information Design for more than 14 years.
I recently attended this year’s Adobe Max Conference. I use Adobe products all the time and thoroughly enjoyed the conference. There were hundreds of sessions. There was also the usual smattering of the famous, the academics, and wonderful artists. My favorites were the practical tips in Illustrator, Photoshop, and After Effects and that’s where I spent most of my time.
My take on this is that there are some exciting new technologies coming out way in AR. I wasn’t that impressed with the 3D tools presented. Considering the additional cost beyond the creative suite (appears to be its own suite), not worth it with all the hype. I’ve recently taken to learning and using Z-Brush and Blender and will be sticking with those. My one big disappointment was the lack of updates and information on Acrobat and Audition. I would love to see more about what the future holds for those tools.
However, the improvements coming to their core software are amazing. The graphic design, illustration, digital painting, and After Effects sessions (as well as Premiere & InDesign) were worth it. I found myself jumping out of sessions on 3D to join other awesome sessions. The social media sessions were worth a note (even if you don’t do much social media) because they had excellent hosts and they were generous with information and tips. Finally, one impressive aspect of the conference is the demonstration of the speed of Apple’s new Computers. If you can view the materials (not sure if you need an account), I recommend taking the time to watch as many videos as you can if you use Adobe products.
I’ve compiled a list of skills that are important to be an effective technical writer and technical communicator. In the first post of this multi-part series, skills discussed were grammar, usage, editing, and the ability to turn data into information that a reader can use to create knowledge. In part 2 we look at additional skills technical writers need for success.
Know Your Target Audience
An underrated skill in technical writing is being able to determine your audience and understanding how to write for them. This starts with a basic overview of the primary audience. Are they the general public or a specialized smaller group such as scientists? Is the target audience all ages over 18 such as a medical provider or is there a specific targeted age group? As a writer define the primary reader for the document and then determine the secondary audience. Who else might read the material either in the future (will the document be archived) and what do they want from it?
Determining targeted information is a great way to write for your reader. Knowing the audience will allow a writer to target the proper age group and education level and increase the readability of a document. A reading index is a great tool on grade and reading level for readability.
Understanding Complex Concepts and Processes
This seems like a basic principle. A technical writer needs to be able to grasp technical concepts, clearly and concisely. In the classes I teach on technical communication, students know I always comment on how clear and concise their work is. Clear and concise writing is extremely important.
How can a technical writer write about a concept if they don’t understand it clearly and concisely? If a concept isn’t clear to the writer, it will come out in the writing. If the writing isn’t concise, you will lose the reader. Remember, more isn’t better in the case of tech writing. It is just more. Too much explanation usually means the tech writer does not understand what they are writing about.
Quality and Accuracy
Writers need to be concerned about quality. To be more precise, accuracy is important. There are times where the work must get out and so some quality is sacrificed. Accuracy should never be sacrificed, otherwise, there can be issues or failures related to the document. This in turn can be catastrophic in a safety or critical process. Injury, harm, or damage can occur to people and property. Can you imagine a mistake on a technical manual for a nuclear power plant or Standard Operating Procedure (SOP) for an industrial chemical process?
Style Guide Knowledge
Style guides are important, especially if a technical writer creates documents for conferences, symposiums, or academic white papers. The use of a particular style guide varies depending on a client/employer, conference, symposium, academic paper, or knowledgebase article. Technical writers should know the difference between APA, CMOS, MLA, and other guides. I’ve even seen the AP style guide used depending on the technical writing assignment.
Did you know there is a style guide for Physics? It’s called the AIP style guide. AIP Style refers to the citation format established by the American Institute of Physics. There are other style guides by the American Mathematical Society, Geological Society of America, American Medical Association, American Chemical Society, and more. Remember, style guides are your friend. They give clear guidelines on how to write for publications and companies. Do some research and see.
Interviewing Skills, SMEs, and Researching
A very handy set of skills any technical writer can possess includes interviewing, interaction with subject matter experts (SMEs), and research. I have met too many people who think writers of any kind sit pensively thinking out the perfect document and work alone, producing masterpieces all by themselves. Too many beginner tech writers feel they can do it alone in the first draft for manuals and then are shocked to find their materials are flawed, grammatically incorrect, or missing information. I have yet to find the perfect assignment handed in after more than a decade of teaching tech writing. Writing just a single draft is not going to lead with quality or accuracy.
The idea of a lone writer is silly. In many of the jobs I’ve held, I was the only writer but I always worked in teams with experts, inventors, engineers, management, certification consultants, and dozens of other stakeholders. So interviewing skills, especially with experts is important. Learn how to interview people. Practice is the best way to learn.
Here’s where research comes in. Not only is research necessary for documentation, but a technical writer should do their homework and research the topic they are interviewing the SME for before the interview. That way they don’t ask basic questions they could find the answer online and waste the short amount of time allotted with the SME. An SME may get frustrates and end the discussion early, refusing to discuss more. That situation makes technical writing more difficult.
Ethics
Ethical obligations are a part of technical writing. A big part. Ethics is in everything from representing technical information efficiently, clearly, and concisely so that the reader doesn’t feel like they have been tricked to avoid major safety concerns and potential loss of life. I consider ethics a skill because not only do you use common sense, a technical writer needs to learn legal implications as well as corporate culture in the organization that they work for to apply a broad scope of ethics.
Think about all the considerations there are for certifications in hazardous environments and what a business or technical writer needs to learn to work in certain industries. Diligence in making sure information is accurate affects all industries from pharmaceutical, oil and gas, nuclear, chemical, utilities, baby furniture, car seats, automotive, etc. Can you imagine incorrect procedural documents in the utilities or nuclear industries? There are also obligations to keep employers’ trade secrets, to the environment, the public, property, copyright, and liability laws. This list can go on and on. Remember, there can be legal repercussions to the technical writer if ethics are ignored.
This wraps up the two-part series on important skills technical writers need for success. There are other skills like software but the type of software used varies from organization to organization. So every writer must decide what they need to learn.
Lu Kondor has worked as a technical writer for more than 20 years for major corporations. She has a Doctorate in Business Management and has worked in a large variety of organizations including entertainment, software, electric utility, manufacturing, oil and gas, chemical, and nuclear process industries. She is an adjunct lecturer in Advanced Technical Writing as well as Information Design for more than 14 years.
In this multi-part series, I’ve compiled a top list of skills that are important to be an effective technical writer and technical communicator. This isn’t an exhaustive list but a basic outline of what most employers look for. Don’t underestimate simple concepts. Keeping things simple makes your job easier.
Many people think they are really good writers but are they? Some writers are masters of prose, others are skilled in non-fiction and essay writing. That’s fine to think of oneself as a really good writer, but not all writing is the same. Anyone who writes for a living across multiple types of writing will tell you that. What you have to ask yourself is; can you write well as a technical writer?
Technical writing is different than prose or fiction. It is also different than business, textbook, or essay writing. Why? The goals of technical writing are different. Even though all types of writing have some things in common, the goal of what is being written is important. The goal of technical writing is to take data, whether raw or correlated, and decide what is important (and order of importance) and what isn’t important. Then turn it into coherent and cohesive information in a clear and concise written manner so that the reader can gain the knowledge they need.
Excellent Writing Skills Are Important
I am often asked by students what kind of skills they need to be a technical writer. The first thing I say is “A technical writer requires excellent writing basics.” This covers two aspects or sub-skills.
Grammar and usage (including ability to edit)
Ability to turn data into information that a reader can use to create knowledge so that the final outcome is to perform a task, learn, or make a decision
The first is grammar and sentence structure. This is basic and almost anyone could guess why good grammar is important. Knowing grammar and sentence structure is the first step to writing a great document. It also allows a technical writer to be able to edit material that comes to them as well as edit what they write themselves.
Do you know what an Oxford comma is and when to use it? What’s a run-on sentence? What is a gerund? These should be simple questions to answer. Remember, employers may ask about your skill sets, or even better, they will test you on it.
Catching Mistakes
Catching mistakes on documents is especially important in situations where catastrophic failure can result in injury, loss of property or life. For every poorly written technical document, there are repercussions even if there isn’t a catastrophic issue, an organization can still suffer a loss of revenue because of deficient documentation. If you have ever bought a product because you read it could do something, and then the product failed to follow the listed specifications, you understand.
The second is the ability to turn data into information that a reader can use to create knowledge. The outcome for the reader is to have enough knowledge to perform a task, learn, or make a decision. The ability to convert data into information for a targeted audience so they can skim for basic information, scan for a particular piece of information, or read word-for-word to learn as much as possible takes practice. All of these methods provide knowledge to the reader. The reader applies that knowledge so that they can decide how to take action. That action may be as simple as performing a task, learning something new, or making a decision.
Performing a task can be simple. How to load software on your computer, assemble a piece of furniture from the local box store, or execute a standard operating procedure (SOP). It can also be complex, such as a SOP that provides a safe method for taking a boiler offline for maintenance, learning what instrument readings to monitor to prevent an explosion, or setting up a temperature transmitter in a hazardous environment.
Learning can take many forms and can be tied to task performance or decision-making. Learning can stand-alone as well. A person can learn for the sake of learning or to build future skills. For example, reading on updated industry certification standards for equipment or learning a new computer network technology. Learning can easily be tied to a variety of technical writing formats. Learning can also come from video, interactive applications, podcasts, or other media. Have you ever watched a video on a newly released phone, tablet, or device just to learn what all the buzz is about? Then you have watched technical writing in action.
Decision-making for a reader is probably one of the more complex aspects of document usage in technical writing.
Many users will need to make a decision on spending money, procuring a service, or taking (or not taking) an action. For example, many process industry engineers read specification sheets to determine if they will recommend the purchase of a particular brand and model of safety device. CTOs may read up on particular enterprise-wide software or hardware investments. Organizational leadership receiving an environmental report passing EPA requirements for environmental hazards may decide no further action is necessary until the next required testing. Still others such as human resources could read a SOP and determine it is missing a newly updated safety standard required by regulators and will take action to have the document adjusted.
There are a number of reasons why users need to make a decision, perform a task, or learn something new. This concept ties in with knowing the target audience of the document and their needs. That is why the best way to begin is to start with the basics. A technical writer that has a strong knowledge of grammar, sentence structure, and the ability to take a broad range of data and organize it in a coherent and readable fashion is at an advantage. But remember, a document needs to be designed not just for the readability of the document’s target audience, but it must adhere to any rules, regulations, and ethics required to make the document clear, concise, and accurate for the user. Lives may depend on it.
Lu Kondor has worked as a technical writer for more than 20 years for major corporations. She has a Doctorate in Business Management and has worked in a large variety of organizations including entertainment, software, electric utility, manufacturing, oil and gas, chemical, and nuclear process industries. She is an adjunct lecturer in Advanced Technical Writing as well as Information Design for more than 14 years.
Usability testing is one of the best ways of evaluating the quality of a document. A technical writer can use usability testing to ensure user-centered writing. Testing validates documentation by examining successful task completion, identifying any critical errors, determining the time it takes to complete a task, reader satisfaction using the document, and collecting recommendations for necessary improvements.
The metrics defined and collected by the technical communicator will determine how to evaluate successful comprehension and task completion. These metrics are generally both qualitative and quantitative depending on how the information is collected and measured. Set up goals for data collection, metrics, and analysis before usability testing. Consider that documentation can be tested using a variety of delivery methods such as smartphones, tablets, computers, printed versions, web pages, etc. Ask yourself how will your end-user most likely use the document?
User observation can be collected using qualitative methods letting a test administrator see how a user will react to the instructions in the document. Are they struggling and need to scroll back and forth? When the tester provides feedback, are they reflecting this in their observations on your document? Each person who tests your document may, or may not, feel that a qualitative aspect is important.
A user’s reaction to document use is important because some users may stop using a document if they need to scroll or turn pages constantly. Others may not. Observation of a document tester is especially important if you are using only a single tester. The smaller the test group, the higher the risk that feedback can be myopic and not reflect all readers’ experiences.
Unfortunately, we don’t always have time or the resources to do usability testing depending on project size, project milestones, release dates, and type of technical documentation. Nevertheless, new technical writers and students should consider even single user basic testing scenarios when they can. Usability testing is a great way for new technical writers to understand what works and doesn’t work in their documents.
Large documentation projects may employ usability testing, especially if there is a lot at stake. Usability testing requires buy-in by management to be successful because of the allocation of resources and stakeholders. Not all management buys into usability testing. Unfortunately, most technical documentation projects are quickly written, updated, or reviewed by someone who may not be an editor, and the document goes out to the intended audience without testing. This isn’t a big deal on a small document but can lead to quality issues in large documents. The importance of testing does depend on the document, purpose, and intended update schedule if any.
One of the best ways to think about the value of usability testing is that you are doing a test run with readers to catch catastrophic issues. This is particularly useful with standard operating procedures (SOPs) or any step-by-step instructions for dangerous occupations, hazardous locations, or safety-related situations. Any document can benefit from usability testing, but technical writing failure is particularly visible with SOPs or instructions. This is critical in industries where a misunderstanding or misrepresentation of data and information can lead to catastrophic failure (loss of finances, loss of property, or loss of life).
To start testing, recruit a pool of participants that fit the profile audience of the readers you are writing for. This provides the best results. The usability testing participants, if possible, should perform the testing under the same conditions a reader would use the document. Even a single qualified participant can help identify any clarity issues a document has.
For students, new technical writers, or small businesses who decide usability testing is for them, I stress using a single reader to save money and time as long as the reader is similar to the intended audience. Only an organization can judge whether they need a large testing sample based on their own usability testing practices and the complexity of their document.
Whatever an organization decides to do with usability testing, remember it is a team effort with all stakeholders. No one works in a vacuum, especially technical writers. The testing process needs both management and the technical communicator’s buy-in to work. Students should use it in their work as often as they can until they get used to writing for a variety of audiences. Remember, if there is a team of technical writers and graphic artists that are designing a document, usability testing can save money by allowing any identified readability problems to be corrected quickly and efficiently before document release. Poorly written documents can reflect negatively on an organization, the technical writer, and ultimately can place a user at risk.
=============
Lu Kondor has worked as a technical writer for more than 20 years for major corporations. She has a Doctorate in Business Management and has worked in a large variety of organizations including entertainment, software, electric utility, manufacturing, oil and gas, chemical, and nuclear process industries. She is an adjunct lecturer in Advanced Technical Writing as well as Information Design for more than 14 years.
Do you like to write and would love to do it for a living? Try technical writing. No need to be a ‘techie’ or scientific guru. With practice, you can find out how technical writing is a great tool in a writers tool box.
Students who want to take the Advanced Technical Communication course so they can get right to creating portfolio pieces (before they take the Introduction course) are welcome to do that. The class is immersive. I teach the Advanced course and we focus on creating a portfolio of pieces (which is normally requested by potential clients and employers) and are a great way to learn how to write even if you want writing as your secret weapon in your job. We write a lot.
Some of the things I cover in the advanced class include presentations, reports, proposals, and step-by-step instructions. Check out my FAQ page for answers to the most asked questions I get in the course. The class is totally online and you will come away with several portfolio pieces. I’ve had students get jobs before they finish the program.
For more detailed info, check out California State University Dominguez Hills’ web site at: