How to Write, Tips
1 Minute Writing Tips – How to Edit a Technical Document (with AI)
May
After hearing his Symphony No. 1 in C minor, Op. 68 performed for the first time, Johannes Brahms is alleged to have said, “I didn’t write this.”
There are different ways to interpret this remark. But for sure, we’ve all written something that, when heard or read back later, sounded very different from what we anticipated.
When writing technical documents, especially those that have gone through multiple revisions, what you initially set out to write and what appears in the review document may differ. In addition, you’re probably fatigued from wordsmithing the text and want to move on to something else. Nonetheless, as your name is on the document, it’s critical that you can stand by what you’ve written.
So, let’s look at how to review a technical document. Before I start, it’s assumed you’ve spellchecked the text, checked your sources, and so forth.
A technical edit serves three purposes:
- Technical accuracy: Check if the material is technically sound.
- Completeness: Confirm that all necessary information is included. No more, no less.
- Comprehension: Ensure that the material is written so that a new set of eyes will understand what you’re trying to say. This mitigates against the curse of knowledge.
# 1 Pen and Paper Review
Use the following approach to review the document:
– Print it out. Your eye will catch things you may have glanced over on screen.
– Get a pen and ruler. Start by reviewing the last line and work your way up, line by line.
– Treat the last paragraph as if it were a standalone document. Does it make sense?
– Repeat this exercise of reviewing the material from the end of the document to the start of the page. This prevents you from scanning through the material, skipping over sections you understand, and racing towards the end. While reviewing, add notes in the margin.
# 2 Vocal Review
Update the document and print it out again. Then:
– Ask a colleague to join you.
– Read the document aloud to them.
– Note any sections where you struggle or where they need clarification. This indicates areas that need revision.
– Alternatively, have them read the document aloud to you. You’ll be surprised how different it sounds when you hear it for this first time, as Brahms remarked above.
# 3 AI Review
Yes, we can (and should) use AI.
NB – Don’t share confidential material online. One workaround is to replace your company and product names before uploading it to CHATGPT et al. If you’re uploading a PDF, remember that metadata may be digested.
1. Go to your AI of choice. I use Gemini for shorter documents such as emails, and Claude for longer material, especially if it’s in PDF format. Enter the following prompt:
“As an expert technical editor, review the following text. The document should be written in US English and align with the Microsoft Style Guide for Technical Publications. Check spelling. Check grammar.
Check for technical accuracy, completeness, and comprehension.
Ensure the reading level is suitable for non-native English speakers.
Identify sections where the flow of the document is unclear.
Identify jargon. Identify acronyms that should be explained.
Provide a revised version of the document.
Avoid AI writing clichés, such as the use of clichéd terms like ‘delve’ or ‘realm.’ Use short words and sentences. Consult the Microsoft Style Guide for Technical Publications.”
Do you understand this request?
2. Click Enter and wait for the response.
At this point, CHATGPT shouldn’t flag any major errors as you should have caught these in the first two rounds of edits. However, there is something else you can do.
3. Go back to CHATGPT and ask it to improve your revised text. Note that I’ve changed the role to Technical Writer.
“As an expert technical writer, improve the following text.
Return the text, paragraph by paragraph, in the following format:
Before: display the first paragraph.
After: display your updated version of the first paragraph.
Repeat with the rest of the text.”
I find this paragraph-level approach works best. It seems to give the AI the opportunity to focus on a specific unit of material rather than analyzing the entire body of the text. I would also add that different AIs perform better with this approach. Increasingly, I tend to avoid ChatGPT and default to Gemini or Claude.
Did this help? Are you using AI to review technical documents?
Connect with us
We’re over here. Say hello at:
