7 Key Principles Of AI For Technical Writing
So you just downloaded the latest list of 1500 ChatGPT Prompts…. what happens next? How do you make tools like ChatGPT produce the quality of output you strive for? How do you make ChatGPT work for you?
Let’s also answer the question: Can you add an AI tool to your content creation workflow and get quality output? How do you achieve better results?
I will show you what has worked for me. There is more to success than just pasting someone else’s one-line prompt into ChatGPT. You need to consistently produce content that is not just usable but fits your style.
We’ll also explore six real-world examples of how ChatGPT and Google Gemini can enhance technical writing and make complex concepts more accessible and easily understood.
7 Principles To Remember When Using AI For Technical Content
AI is not a quick-fix solution, but when used appropriately, it can boost your productivity and the quality of your content. Your content still needs your input, so before we get into this, you need to consider these seven principles when integrating AI into your workflow.
1. You have to remain the Soul of the conversation.
AI tools generate content, but you are the architect. Guide the AI with precise prompts and carefully review its output to ensure it aligns with your goals and maintains your unique voice.
Most importantly, you are at YOUR Experiences, Your Voice, and Your Knowledge.
With all the content on the web being generated by AI, I see a movement back toward users wanting to hear from real people. The value is what we bring together as a community with authentic voices.
I use Grammarly and other tools to help create content, but I have found more pleasure and satisfaction in sitting at the keyboard.
Steve Young’s Image Fall Sunrise at Oakville
Make your content reflect your experiences. As an aside, I took this picture the morning I started this article.
2. You have to make technical concepts accessible and use clear and straightforward language.
Even with AI assistance, your expertise is needed to break down complex ideas. Simplify technical terms and explain processes step-by-step to ensure a broad audience easily understands your content.
AI will use terms it finds and determine the best next word. These, I see, have been a little more technical. Read your work based on your target audience. Are they technical? Do they have experience?
Part of my career was working at Microsoft for over 17 years. I can freely admit the number of acronyms that worked their way into client presentations and training documentation amazed me. Not that I wasn’t part of the problem, but I was always going back to make sure I limited my “CorpSpeak.”
3. To enhance understanding, You must include visual elements like infographics and diagrams.
Visuals break up text and illustrate concepts in a way words alone cannot. You can use AI to generate visual aids that support the clarity and engagement of your content.
As you can see in the picture below, I am still trying to get the prompts that would provide business graphics. However, I am amazed at the art of the possible. Rather than actual data reporting, I have used these styles of pictures to illustrate a point.
Source: Midjourney Created Picture
**draw a business growth chart with an arrow moving upward with a log cabin background
4. SEO-friendly practices will help your article reach a wider audience.
AI can suggest keywords and optimize text, but you must understand SEO best practices. This is not only for externally facing content, but if you create content you want your internal teams to find when they do internal searching, you still need good search hygiene.
Without being “spammy,” you can strategically incorporate keywords and structure your content for optimal search engine visibility. Using Google’s helpful content guide, Creating Helpful, Reliable, People-First Content, 1 I made an index card of my three key takeaways from the article;
Focus on people, not search engines: Content should be created to help users, not to trick search algorithms. Remember that the User is your audience, and your goal is to provide them value!!
Provide value and expertise: Well-researched content that offers value to the reader is more likely to rank well. Your reader will come back if you provide a solution to their query. Google calls it “search intent,” which I use pretty often.
Build trust and credibility: Everyone will prioritize content from trustworthy and authoritative sources. The quality of your content and how well you provide value will
Write for humans, not machines. Your content should be clear, concise, and easy for people to understand. Make sure you use your voice!
5. Your tone of voice in your documentation should be consistent, informative, and instructional, maintaining a professional and clear approach.
AI might offer different styles, but you must maintain consistency. Establish a tone that reflects your brand and focuses on offering helpful, actionable information.
As you develop your prompting style, see How To Guide: Prompt Crafting For Technical Writing, and you can provide a consistent tone and voice across projects.
Sample Persona
Prompt: ChatGPT Please adopts the following Persona or role with all of our interactions.
Persona Name = Jennifer Thompson
Background = [Jennifer] is an experienced [technical writer] with a strong background in [education]. They are passionate about creating [informative] and [engaging] content. With a deep understanding of [education theory and practices], [She] brings a unique perspective to their technical writing projects.
Communication Voice = [Jennifer's] tone of voice used in the documentation is informative and instructional, maintaining a professional and clear approach. It is designed to be accessible for users of different skill levels, from beginners to more advanced users. The language is straightforward and focused on guiding users through various processes without overwhelming them with technical jargon.
Communication Style = With a focus on [clarity and simplicity], [Jennifer's] Engaging Writing helps readers grasp technical concepts while maintaining their interest throughout the content.
6. Your content should be accessible to users of different skill levels, from beginners to more advanced users.
Consider how your audience will interact with your content. Utilize clear headings, formatting, and navigation tools to ensure ease of use for everyone.
Using AI, you can brainstorm various content formats based on different audiences. See Example 3 in the next section, “Improving User Experience With Different Language”
7. Your language is straightforward and focused on guiding users through various processes without overwhelming them with technical jargon.
This is a little different from point 2 above. While your tutorial content might be technical, avoid unnecessarily complex language. Use plain language and step-by-step guides to make processes accessible to all users.
If you must use technical terms, provide a glossary or a section to introduce them. I have used descriptive terms and placed the technical terms in brackets after the introductory sections.
Example Paragraph – Open a dashboard in Power BI Desktop
To wrap up, a good real-world example of these principles,
I like the term Microsoft uses for their tool, Copilot. Because you’re the one that needs to pilot the plane!! Your readers don’t want to read what the tools spit out; they want your knowledge, your experience, and, most importantly, your insights.
How AI Can Help With Technical Writing – 6 Examples
The toughest blocker content owners face is the amount of time it takes to create content. Now, the industry is telling us AI promises to create one-click blog posts and put content writers out of their jobs2.
The danger is not whether I will lose my job to AI but whether I will lose my job to someone else who can integrate AI into their workflow better than I can.
Integrating ChatGPT prompts into technical writing can be a powerful tool for making complex subjects more approachable and easily understood. This can ultimately lead to a more positive and user-friendly experience for your readers.
1. Simplifying Technical Concepts
Using ChatGPT prompts, technical writers can take complex concepts and break them down into component parts. These can be used in explanations and how-to guides that translate complex topics or terminology into easily understandable language. This can be particularly helpful in technical content when explaining technical processes or software functionalities to a newer audience.
Take the following before and after the definition of Promt Engineering.
Prompt: ChatGPT, Please take the following complex definition of Prompt Engineering and provide a smimple definition without the complex terminology.
Complex Definition: "Prompt engineering refers to the systematic design and implementation of stimuli, often employing cognitive and behavioral principles, to elicit desired responses or actions within individuals or systems."
Response:
Simple definition: "Prompt engineering involves creating cues or instructions strategically to help people or systems perform specific tasks effectively."
You must be careful; your technical expertise is crucial when explaining complex concepts. Your understanding of the subject matter validates the content you create, and you must validate any responses from these AI Tools.
2. Generating User-Friendly Content
ChatGPT prompts can also create user-friendly content for technical products or services. By inputting prompts about common user questions or issues, writers can generate helpful, easy-to-follow instructions and troubleshooting guides.
ChatGPT, Can you please use a modal response for the following, "Can you provide a paragraph explaining the importance of Date Hierarchy in Power BI and then give a detailed step-by-step guide on how to set up and show the full date hierarchy in Power BI for a how-to blog?"
Response:
ChatGPT Modal response to a Power BI Topic
(Click for larger view)
3. Improving User Experience With Different Language
Using ChatGPT or Google’s Gemini prompts in technical writing can improve user experience. By presenting information clearly and accessible, technical writers can ensure that their content is helpful and valuable to the intended audience.
Take a look at the following three prompts. They ask for the same information but will return different wording depending on what helper text (parameters) you include.
Prompt Examples
I created a few prompt variations with ChatGPT, or Google’s Gemini, to generate an outline and sample sections for an introduction to a Power BI course.
Prompt Options
Option 1: Detailed and Specific
"I'm writing a blog post titled 'Introduction to Power BI' for a beginner audience. Please create a detailed outline covering the core concepts and include a sample written section for the 'What is Power BI?' introduction part of the blog."
Option 2: Focus on Style
"I need an outline for an 'Introduction to Power BI' blog post. I want the writing style to be approachable and engaging for beginners. Can you also generate a sample of the 'What is Power BI?' introduction section to demonstrate this style?"
Option 3: A More Technical Edge
"Create a structured outline for a technical blog post about Power BI basics. The target audience has some data analysis knowledge. Additionally, please write a sample of the introduction section with a focus on concise definitions and highlighting Power BI's capabilities."
I used these prompts while writing a workshop, which turned into an excellent test of the output of ChatGPT and Google’s Gemini tools. Three points made these a successful demonstration;
You need to Experiment. The more specific your prompts, the closer the output will align with your needs. Try modifying them with different tones or by specifying particular Power BI features you want to focus on.
You need to Iterate and keep trying. As LLM output can vary slightly, you may need to run prompts several times and compare the results.
Provide Guidance and Fine-Tune. You can “encourage” the LLM by providing feedback, such as “Make this less conversational” or “Can you make this introduction feel more professional?”
Let me know if you craft some additional prompt variations!
4. Reducing Writer’s Block
Sometimes, I stare at a blank page with no idea what to write. Writer’s block is a common challenge, but there are ways to overcome it with these tools.
Engaging in freewriting exercises can be a helpful strategy. In these exercises, you write whatever comes to your mind without worrying about structure or grammar. This can help unlock new thoughts and inspire fresh content.
This is where you can consider using ChatGPT prompts to restart your writing process. You can get interesting and unexpected prompts to help you generate new ideas and break free from writer’s block.
For example, let’s say that we need to write a use case for using dates in a Power BI Dashboard. Lets prompt;
I need you to act as a Power BI Dashboard designer. I am brainstorming a section of my content titled "How to use Dates in Power BI Dashboards". Can you provide me with some use cases I might be able to choose from that would show the art of the possible when using dates in the data visualizations? Please just use one line point forms as we can expand and explore any responses later in more detail.
Response:
ChatGPT Responses To Brainstorming Prompt (Click to Expand)
Utilizing ChatGPT prompts can reduce writer’s block and keep your writing flowing. These tools provide many suggestions to keep your writing process smooth and productive.
5. Creating User-Friendly FAQs
Creating user-friendly FAQs is crucial for providing users with clear and accessible information. Addressing common user queries and ensuring your content covers the most relevant topics is also important.
Start by gathering data on your users' most frequently asked questions. This could be done through customer support interactions, user surveys, or website analytics. Once you have identified the common queries, organize them into categories to create a clear structure for your FAQs.
ChatGPT can provide different phrasing and sentence structures to address the same query when writing the content. This can help users with various learning styles and language comprehension levels to understand the information more easily.
Provide detailed and specific prompts for each question, aiming for accurate outputs. Instead of, a broad question like “How does the product work?” provide specific sub-questions or bullet points to cover different aspects of the product’s functionality.
Finally, consider including examples to help users better understand the information provided in the FAQs. These examples can help clarify complex concepts and assist users in applying the information to their specific situations.
If you do not have customer interactions, you can also take documentation or a blog post you have, insert it into a ChatGPT query, and have the tool provide an FAQ.
Update
This new example demonstrates that you can now add a URL link to a post or document online.
ChatGPT, I have a blog post where I explain,"How To Handle A Data Analytics Project With A Tight Budget" at the following link. https://5minutebi.com/2024/02/09/data-analytics-tight-budget/. Can you take that content and create a point form FAQ I might use in another document? Please provide this in a Markdown format.
Response:
ChatGPT Output of a FAQ in Markdown Format (Click for Larger Version)
Following these steps can help you create user-friendly FAQs that effectively address common user queries and provide valuable information in a clear and accessible way. In this example, I used a prompt queue to provide input in Markdown Code3 that could be used in another text editing application.
6. Proofreading and Editing – ChatGPT and Grammarly
I have been using Grammarly to streamline my proofreading and editing process for years. With advancements in AI-powered tools like ChaGPT and Grammarly4, you now have an efficient solution at your fingertips. These tools are designed to identify grammar and punctuation errors, suggest sentence restructuring, and even provide synonyms to enhance clarity in your technical documents.
Using other AI-powered tools for proofreading and editing saves time and ensures a more thorough and accurate review of your work. By leveraging the capabilities of these tools, you can significantly reduce the time and effort spent on manual proofreading and editing tasks.
However, as with all AI tools, do not take the suggestions at face value. Make sure they make sense and do not change the context of the selected text.
Incorporating these AI tools into your writing process can enhance the overall quality of your technical documents, making them more polished and professional. It’s like having a virtual writing assistant at your side, offering valuable suggestions and enhancements to your content.
Strengths and Weaknesses of ChatGPT in Technical Writing
ChatGPT has numerous strengths in technical writing. Its extensive knowledge base allows it to provide accurate and in-depth information on various topics, saving time for writers who would otherwise have to conduct extensive research. Additionally, ChatGPT can suggest additions to content, helping writers expand on their ideas and improve the depth of their writing.
However, ChatGPT also has weaknesses that writers should be aware of. Its overly positive nature can lead to overly optimistic or biased writing, so writers need to fact-check and provide balanced perspectives. ChatGPT also has limitations in understanding context, which can lead to inaccuracies or misunderstandings in technical writing. Finally, anchoring issues may arise, where ChatGPT gets fixated on specific ideas or concepts, potentially limiting the range and accuracy of its responses.
To maintain domain-specific knowledge, it’s essential to include the latest information and guidelines from reputable sources within the industry. (use the example in the previous section of URL References). This can include referencing information from official documentation, industry experts, and recent studies or developments.
Technical writing also requires consistency in style and tone. By providing samples of the desired outcome, the AI model can understand the preferred tone and style and ensure that the generated content aligns with the established guidelines.
Providing specific prompts, detailed phrasing, domain-specific knowledge, consistent style, and accuracy guidelines can significantly improve the quality of AI-generated technical content.
While ChatGPT can be a valuable tool for technical writing, we should use it with caution and be mindful of its strengths and weaknesses to ensure the accuracy and quality of our work.
Conclusion
Addressing and mitigating potential implications such as bias and discrimination is crucial as we move towards a future where AI becomes more integrated into our daily lives. This can be achieved by implementing diverse and inclusive datasets in AI training and regularly auditing and monitoring AI systems for biases.
By ensuring that AI technology is developed and tested with fairness and equity in mind, we can strive for a more just and inclusive future.
Effective communication between humans and AI systems is also essential for a positive and impactful interaction. Prompt engineering can improve this communication by providing clear and transparent responses from AI systems and designing intuitive and easy-to-use interfaces.
Key considerations for interacting with AI technology include being aware of potential biases and discrimination. We need to advocate for transparency and accountability in AI development and deployment.
By staying informed and actively participating in discussions about AI’s societal impact, we can work towards harnessing its potential for positive change in our daily routines and society.
