Nederlands
Blog series “Technical documentation and the power of AI”
It is the talk of the day: Artificial Intelligence, also known as AI. Whether it’s at the coffee machine at work, or during dinner with the family – The rapid development of AI is what everyone is talking about. From the huge impact it already has on our lives to the undiscovered possibilities (and challenges) that lie ahead. How does this affect our work and daily life?
At Foxiz we’re full of questions and ideas. By now, AI is part of the job for our technical writers, illustrators, translators, and consultants. We would like to take you with us on our journey of discovery. The thing is, we want to tell you so much; one blog simply doesn’t suffice. That’s why we’ve written an entire series of blogs on the matter, in which we highlight the different aspects of our job, as well as the impact AI has. Follow along as we explore AI.
Nr. 1: Writing smart prompts with AI
A handy help for those just starting out, but also useful for writers who already implement AI. AI tools such as ChatGPT, Copilot, etc. can be incredibly helpful for technical writers. Such tools can help to simplify complicated texts, change the tone of voice, or make sure that your manual adheres to the applicable standards and guidelines. The result however isn’t always exactly what you need, it depends heavily on the quality of the prompt you gave AI. In other words: what you ask for, is what you get.
How do you optimize AI tools for technical documentation?
Want to know what can go wrong?
Let’s take a look at the effect of a short and simple prompt. The image below was generated by AI and now we want to highlight the control panel. To do so, we enter the following prompt:
“Mark the control panel underneath the radar screen with a red frame [ship.png].”
How do you write a proper prompt?
Everyone has different opinions and answers to this question, and with every new version of AI, something changes. There is, however, one thing everyone is certain about: AI needs clear guidelines. See the example below for the guidelines most often used to get better answers and results from AI:
Role: Give AI a role, this provides a clear starting point.
Goal or task: Give a clearly written goal or task to improve the output.
Context and background: Give a clear description of the situation and background information so AI has some context in which to place the question.
Output example: Give an example of the expected output.
Output format: Indicate the format in which you want to receive the output.
Ask for confirmation: Working with AI is an iterative process, save time and money by reducing content analysis.
Sounds easy enough, but what does a prompt like that actually look like?
The rest of the image should be left unchanged.
If the GPS screen and control have been clearly identified.
If the PNG-format is possible and the desired style is clear.
Let me know if something is unclear.
What is the effect of this new prompt?
The difference can be seen immediately. The steering wheel is still in its position, the GPS screen and buttons are no longer highlighted in red, and the control elements beneath the radar screen are now framed with a red line, exactly like we asked.
Examples of good and bad prompts
Having a list with your own favourite prompts helps you work faster. You just have to adapt them to the specific situation. This way you can create your own AI style guide as a technical writer. See the table below for a quick overview:
| Bad prompt | Why is it unclear? | Improved prompt |
|---|---|---|
| “Write a manual.” | No subject, target audience or length. | “Write a short manual (max. 200 words) for a coffee machine, aimed for daily use by consumers.” |
| “Explain this.” | No context: what needs to be explained and to who? | “Explain in simple B1 language how a mechanic inspects a fire extinguisher. Use a maximum of 5 steps.” |
| “Rewrite this.” | Too vague, no target or style. | “Rewrite this text in clear instructions; use active sentences and a list of max. 4 bullets.” |
| “Translate this.” | Unclear to which language or with which tone of voice. | “Translate this to German and keep the formal tone of voice. Use short sentences (max. 12 words).” |
Finally, some practical tips:
Start simple, but be clear
A prompt is nothing other than an instruction. The usability of the output depends on how specific you are.
Work iterative
A prompt does not have to be perfect on the first try. Look at it as if it were a conversation:
- Start with a first version.
- Check it to see what is already correct and what needs to be changed.
- Ask for specific adjustments.
Example:
- “Can you please shorten the text and make a list of 3 bullets?”
- “Use active sentences instead of passive ones.”
- “Translate this to German but keep the layout.”
Experiment with rolls
You can ask AI to take on a specific role. This is specifically useful when creating technical documentation.
Examples:
- “Imagine you are an experienced safety inspector. Explain how to test a gas detector.”
- “Pretend to be the end user and ask critical questions about this manual.”
This often leads to surprising new insights.
Ask for structure
As a technical writer you’re often looking for a structured output. You can achieve this with your prompt.
Example:
- “Provide output with the following layout: Title, Introduction, Step-by-step plan, Warnings.”
- “Use a table with columns: Step number, Action, Note.”
This way you prevent messy output, and you save time post-processing the final product.
Limit or enhance creativity
Sometimes you need a factual text, other times you need more creative varieties.
Example:
- Factual: “Create a list of just the steps, without further clarification.”
- Creative: “Give 5 alternative options for the titles of this paragraph, with a lighthearted tone.”
By explicitly mentioning certain things, you can steer the output.
Think of language and style
As a technical writer you’re often thinking about the tone, clarity and consistency of your texts. AI can help you guard these for you, if only you ask.
Example:
- “Rewrite this in simple B1 Dutch.”
- “Use short sentences (max. 12 words).”
- “Avoid technical jargon and explain terms in a single sentence.”
Foxiz and AI
At Foxiz we implement AI in a safe, smart and effective way to aid our specialists with their work on technical documentation and translation. This way we create high quality technical content. Combining the best of both worlds!
In need of proper technical documentation for your product or system? Want to pick our minds on how to improve your documentation and its translation? Or are you interested in a job as technical documentalist? Please contact us! We are happy to help you.
TIP: Our next blog answers the questions if and how you can gather information using AI. Stay tuned!