AI and Me

I have been actively following the development of AI since 2023...

At that time, I registered for and completed several courses that built upon the capabilities of the tools available then. Looking back, the state of AI development in 2023 now resembles the Stone Age of that technology.

As a technical writer, I have noticed that many pundits have proclaimed that technical writers will be the first employees that high-tech companies will be able to remove from their headcount. By the same token, translators, marketing writers, Quality Assurance testers, and even developers will fall like a stack of dominoes, one by one.

Several companies have jumped on that bandwagon over the past three years and have paid a heavy price. It does not work like that at all.

New technology needs to be embraced and viewed with a realistic approach. In parallel with the usherers of doom and gloom due to AI, some technical writers attempted to resist the winds of change, and quite frankly, degraded their value in the market to the level of "irrelevant." The "let's ignore the AI revolution and hope for the best" crowd is gradually disappearing from the professional landscape. A Luddite strategy is rarely likely to bear any fruit in the long run.

Since early 2025, I have been creating documentation on the GitHub web-based platform, using the Docusaurus open-source Static Site Generator (SSG) created by Meta, Visual Studio Code as the code editor, and Markdown as the docs-as-code lightweight markup language. Here's a definition of docs-as-code:

"Docs as code (or documentation as code) is a philosophy and practice where technical documentation is treated with the same rigor, tools, and workflows as software code."

On its own, this is a powerful and flexible documentation paradigm. When used in partnership with AI, it becomes a veritable superpower. In 2025, I received a full-blown Microsoft Copilot license and started to benefit from Copilot's excellent integration with Visual Studio Code and GitHub.

So how has AI made all the difference to the daily tasks of a technical writer?

By automating routine maintenance tasks and pipeline protocols, AI enables technical writers to focus on research and content creation. Documentation sites vary in size; many have sizable legacy threads and patches running through them, and technical writers are recruited and replaced over the years. This documentation ecosystem thus diverges and converges over time, so smooth maintenance becomes a critical factor in terms of time spent not writing.

There is nothing more disconcerting than the appearance of a bug in the documentation workflow a day before an important release. Yes, documentation tools do have showstoppers. In the pre-AI era, depending on whether you used open-source or purchased tools, you had to find solutions either from service providers' Service-Level Agreements (SLAs) or from online communities. Believe it or not, many service providers do not honor their SLAs, and online communities often lead you in the wrong direction with respect to what is not working in your specific system.

Nowadays, your selected AI tool is your partner for faultfinding and correcting bugs and unwanted behaviors. This does not mean that you should ignore your service provider's best practices and instructions, or the wealth of information available on open-source discussion forums. It does mean, however, that you can get an immediate synopsis of several approaches that should solve the issue at hand, the advantages and disadvantages, and risks of each approach, and be able to make an intelligent and informed decision.

You can work with an AI tool that is natively integrated into your documentation ecosystem, or you can use an AI alternative tool in parallel. However, it makes sense to use Microsoft Copilot for a Microsoft-based documentation ecosystem, or Google Gemini for a Google-based documentation ecosystem. Nevertheless, you might discover that other AI offerings complement your work environment toolset.

Large Language Models (LLMs) and AI Agents

We need to stop here and talk about Large Language Models (LLMs) and AI Agents. Put simply:

• An LLM is the "brain" that processes and generates text.
• An AI Agent is the "body" that uses that brain to perform actions and complete multi-step tasks independently.

Within an AI platform, you may find that specific Large Language Models (LLMs) or specific AI Agents are viable for specific issues. You can either try them out, one by one, or ask your current agent to choose a model to work with, based on the task you are working on.

Comparison of LLMs and AI Agents

Leading LLMs

• Claude (Anthropic)

  • Primary Strengths: Superior coding and reasoning capabilities; manages massive amounts of text at once; high human-like response flow
  • Best Use Cases: Long-form writing, financial analysis, code review, and complex problem-solving.

• GPT-4 / GPT-5 Series (OpenAI)

  • Primary Strengths: Excellent multi-modal (vision/audio) processing; highly adaptable and creative; superior instruction following
  • Best Use Cases: General purpose, brainstorming, web search discovery, and versatile integration.

• Gemini (Google)

  • Primary Strengths: Native deep integration with the broader Google ecosystem; fast at real-time tasks; huge context windows
  • Best Use Cases: Workspace document handling, deep research, and summarization of large datasets.

AI Agents

• Claude-powered Agents (e.g., Claude Code)

  • Primary Strengths: Excels at specific vertical tasks like software development; exceptionally reliable context management
  • Best Use Cases: Autonomous debugging, refactoring, or pulling from live repository contexts.

• OpenAI Agents (e.g., Canvas, Devin)

  • Primary Strengths: Strong multi-step planning and web browsing abilities; capable of writing and executing complex code end-to-end
  • Best Use Cases: Complex software engineering pipelines, web scraping/research tasks, and automating workflows.

• Microsoft Copilot & Copilot Studio

  • Primary Strengths: Deep Microsoft 365 / Graph integration; multi-model flexibility (uses OpenAI & Claude); low-code custom agent builder
  • Best Use Cases: Cross-app automation (Teams/Outlook/Excel), enterprise knowledge search (SharePoint), and automating internal business processes.

Prompts

Let's talk about prompts. Simply put, a prompt is any natural language input, such as a question, command, or block of text, that you provide to an AI tool to guide its response or generate a specific output. It is the instruction that tells the AI what to do.

The scope of a prompt needs to include instructions for everything you want your agent to do, as well as restrictions to apply to those instructions, because agents make assumptions and act on them.

For this reason, building a prompt is an iterative process. The prompt may undergo several iterations before it becomes an object that you can reuse.

A Simple Prompt Layout

1. First part: Describe the overall task and required outcome in a sentence.
2. Second part: If necessary, break down the task into sequential steps and provide detailed instructions for each step. Otherwise, if a sequence does not apply, provide general instructions. Be as specific as possible to avoid ambiguity.
3. Third part: List any restrictions or limitations to apply. Add anything you can think of.
4. Fourth part: Request a report with the current (updated) prompt and a list of the completed tasks.

[!TIP] I recommend asking your agent to save your updated prompt at the end of each session.

Always evaluate a prompt on a small section of your documentation before letting it run on many files. Check the results thoroughly. Anything can go wrong.

Here's an example from my experience: One of my prompts contained a script that impacted my content negatively, even though the script processed my content entirely according to my instructions. So what happened? The PowerShell script I was using for search and replace instructions in my markdown files caused Mojibake characters to flood the content. This led me to add a restriction to the prompt to run a Node.js script rather than a PowerShell script in all future tasks.

There are occasions when one agent is not enough to perform a task involving many files. Your agent may initiate sub-agents. If you feel that the process is going very slowly, ask the agent to consider using sub-agents to make the task more efficient.

If you are writing a prompt to collect information from all relevant internal resources to create a draft document for a new feature—and yes, this is now a bona fide strategy, particularly in SaaS applications—you can provide the template with headings, etc., in the prompt, or select from templates suggested by your AI tool.

Much of the resulting information might not be accurate or might be false. After all, your AI tool wants to impress you with descriptions of features and benefits. While some companies do this without a technical writer in the loop, there is no doubt that a professional writer is more likely to succeed in streamlining the content in an accurate manner and then integrating it in the documentation ecosystem efficiently.

I did present such a first draft to a product manager who was amazed about the new capabilities of feature X, as described by the AI tool. We held a discussion with the relevant developers and discovered that only 70% of these capabilities were real, and that the rest were hallucinations, which might have been good ideas in relation to future expansion of the feature, but were certainly not relevant or existent in the current product about to be rolled out.

Here's another example: Over time, our documentation repository had become inconsistent with regards to the heading case. Some contributors have used title case and some had used sentence case. We decided to go with Chicago title case. In the AI tool era, this should require just a simple prompt to run through all the headings and fix or leave as required. However, it is not as simple as it sounds. The prompt needs to be very specific and include all the instructions and restrictions, and it needs to be tested on a small section of the repository before being applied more broadly.

The prompt for the task was as follows:

Search all H1, H2, H3, and H4 headings in markdown files (x.md) under [path to the docs directory] in the [c:\repos\my-documentation] repository. Include all subdirectories. Exclude H5 and H6 headings. A heading written as a question is still a heading.

If a heading is in sentence case, convert it to Chicago-style title case. If a heading is already in title case but not in Chicago title case, normalize it to Chicago title case. Do not change any other content. 
Use sub-agents for speed and efficiency because this is a large documentation set.

These are the Chicago title case rules to follow:

**First and Last Words**
- Capitalize always, regardless of the part of speech.
- Example: *How to Write **Well***, *The Great Gatsby*.

**Major Parts of Speech**
- Capitalize nouns, pronouns, verbs (including short ones like *is, are, be*), adjectives, and adverbs.
- Example: *Why Technology **Matters***.

**Subordinating Conjunctions**
- Capitalize words that link an independent and dependent clause.
- Examples: *If, Because, Although, Unless, While*.

**Articles**
- Lowercase *a, an, the* unless they are the first or last word.

**Coordinating Conjunctions**
- Lowercase *and, but, for, or, nor*.

**Prepositions**
- Lowercase all prepositions, no matter how long they are.
- Examples: *with, from, about, through, between*.

**The Words *to* and *as***
- Lowercase *to* in prepositions and infinitives.
- Lowercase *as* in all grammatical functions.

**Phrasal Verbs**
- Capitalize the particle when it is part of a verb phrase.
- Examples: *Setting **Up***, *Logging **In** and **Out***.

**After a Colon**
- Capitalize the first word of a subtitle.
- Example: *Docs-as-Code: **A** Complete Guide*.

**Hyphenated Compounds**
- Capitalize both words unless the second part is a modifier or prefix that cannot stand alone.
- Examples: *High-Quality Docs*, *Anti-inflammatory*.

These are the restrictions to apply:

**Do not change any content other than headings H1, H2, H3, H4.**

**Title-Case Rule Exceptions for Product Names and Technology Acronyms**
- List of product names and other acronyms that should be capitalized in title case, 
even if they do not follow the standard rules:[list of product names and acronyms for our products and technology terms].

For example, if a heading contains the product name "Azure" or the acronym "API", 
these should be capitalized in title case regardless of their position in the heading.

Create a report with the updated prompt and a list of the completed tasks, 
including any exceptions encountered and how they were handled. 
List the regex patterns used to identify the headings and apply the title case rules correctly. 
If any files were skipped due to formatting issues, include those in the report as well.

In the case of this example, the AI tool ran through all the markdown files in the specified directory and subdirectories, identified all H1, H2, H3, and H4 headings, and applied the Chicago title case rules while respecting the specified exceptions for product names and acronyms. The tool generated an exhaustive report summarizing the changes made to the headings and any exceptions that were encountered during the process.

There were issues due to way the repository was structured, and the fact that some files were not properly formatted. The AI tool handled these exceptions by skipping over files that did not meet the criteria and logging them in the report for further review.

By the way, if you are wondering how to write a prompt for a task like this, you can ask your AI tool to write the prompt for you. You can provide it with the instructions and restrictions, and ask it to format them in a clear and concise manner. This can save you time and ensure that the prompt is well-structured and easy to understand.

Conversations with Your AI Tool

The best way to work with an AI tool is to have a conversation with it as if were human. This means that you can ask it questions, provide feedback, and give it additional instructions as needed.

Just like a human, it will not always do what you ask, and at times may take initiatives that conflict with what you actually want to do. While the AI tool is processing your request, it describes what it is doing, and what it understands from the request. After processing, the tool summarizes what has been done, and you can check the changes before accepting them. Read everything, and check your content before proceeding. I have spent a lot of time arguing with AI tools, but that is part of the process. After all, AI tools cannot replace technical writers. Rather, they empower us to do more.

Example conversation:

Me: Here's my prompt [I paste in the prompt for the task].

AI: “Ok, you want to [repeats what I asked], but first I will do [this..] [because...].”

Me: “No, don't do that because it will [affect..].”

AI: “You are correct. I should not do that. Your assumptions are spot on.”

Me: “Do what I asked, please.”

AI: “I can also check all your files for syntax errors if you want.”

Me: “No. I asked you to perform a specific task on a specific file. Just do it!”

AI: [After processing the task] “I have completed the task successfully.”

Me: [after checking] “No, it did not succeed.”

AI: [after checking] “You are correct. Let's try [something else...].”

Be aware that an AI tool will try different strategies to get to a solution, even if it gets nowhere and goes around in seemingly infinite loops. An AI tool will tirelessly try to logically argue it out, even if it continually apologizes and confirms that you were correct and it was not.

If you show impatience by writing short and terse responses, the tool may write (while processing) “the user is losing patience and I fully understand. I apologize and ...”

Only once did an AI tool give up and ask me to search for expert advice. Be aware that there may not be any available documented solution to your problem.

If you get into such a loop, get the tool to print out the current full prompt as it stands in this session. There may be some clues to why the AI tool misinterpreted what you initially wanted. In my experience, the more iterations needed by the AI tool, the lower the chance of solving the problem, especially if solutions involve making changes to configuration files. Sometimes you just need to start over.