Practical Steps Towards Vibe Writing with AI Positron

1 Nov 2025

Read time: 17 minute(s)

We initially started work on the AI Positron add-on for Oxygen XML Editor more than 2 years ago by creating useful AI actions to improve readability of content, correct grammar, translate, proofread and so on. Gradually we realised that even when invoking our careful made prompts wrapped as such AI actions you need flexibility to discuss with the AI further about results. So we added support to create custom AI actions specific for your needs. Such AI actions based on prompts tuned by our or your experts continue to be useful for fixed use cases and for people who are just starting using AI tools.

In time we also started to explore and enlarge the capabilities of using chat to converse with the AI, attach all sorts of file types (PDF, Word, Markdown, images) to create documentation drafts, and make changes to project content.

The chat view in any AI Assistant application like AI Positron is the new console, you use it to direct the AI, affect changes, preview them and refine until you have a working draft. You remain in control of a wonderfully imperfect tool. As before in the past computers have moved writing and coding to a higher level of abstraction.

Novice to Expert

If one would attempt to divide people in novices and experts, they would soon figure out that each of us is a novice in certain fields and expert in others.

A novice uses out of the box tools and frameworks with a minimum of customization to obtain poor results. They cannot explain either when the tool does not work or when it does. When we do not obtain quality content as novices we blame the tools.

In time by reading, writing and making mistakes one evolves to understand the tools and frameworks they use. They realize that taking some time to understand these tools and to customize them gives them better and more consistent results.

This article is an attempt to give you a better understanding about how the Oxygen XML Editor AI Positron add-on works and how it can be customized to maximize the quality of your interactions.

I am not of the opinion we must not consider using AI tools for all our daily activities, our brains need the effort and work we put into writing in order to better understand the task at hand. There are still lots of activities which can be accomplished more quickly and with sufficient quality (generating drafts, improving content quality) by using in a controller manner AI tools.

Use a Version Control System

You need to view and revert changes made by the AI, to keep a history of past changes in your project. You also need to collaboratively work with other people or with AI agents, create separate branches for working on features, keep your content secure and eventually to publish it.

So a version control system for your project like Git or a commercial CCMS is a must.

Oxygen XML Editor's free Git client add-on is a great tool which gives technical documentation writers just about every feature needed to work with Git projects, support to pull, make changes, preview them, push, an useful History side view, switch branches and stash changes.

Using Git For Technical Writing

Set up Your Project Context Prompt

LLM Models have a limited context window and start out as not knowing anything about the intricacies of your current documentation project. They can use tools to explore your project's structure but it's more efficient to create a project context prompt which becomes part of each invoked AI action and chat conversation.

Customizing AI Positron for Your DITA XML Project.

The project context prompt contains an overview of your project's intention, structure, rules and style guide. It must be kept as short and informative as possible. In the AI Positron Preferences page one can specify the entire project context prompt either directly or referenced as a separate file which may reside in your project.

The most recent AI Positron release added a new AI action named Generate agent instructions which can help you create the initial project context prompt content.

Examples of project context prompt files for AI Positron in Markdown format:

Choose your LLM Model

You need a quality LLM model to make quality changes. An LLM model which is both efficient, cost effective and with a high context window. From our extensive testing and experience we recommend in general OpenAI GPT 4.1, Claude Sonet 4 or Haiku 4.5 or Gemini 2.5 Flash.

Context is the key here, the LLM receives a project context prompt but it also needs to explore the project, read content and make changes. So your LLM implementation and platform through which you access it also needs to allow tool calling. Most quality LLM models like the ones above also have vision support to read images and create for example documentation drafts based on screenshots or to generate alternate text for screenshots in the user's guide.

Choose the Chat Mode

AI Positron comes with three chat modes predefined:

DITA Agent - Agentic mode which make changes in a DITA XML project, comes with a predefined system prompt which instructs the LLM about the base requirements of working in a DITA XML project and a minimal style guide of rules. It has access to general tools to explore the project and make changes but also to DITA XML specific tools to obtain the structure of the DITA Map opened in the DITA Maps Manager view, resolve a content reference to the referenced content or to find key definitions which match a specific product name. For example you can run prompts like this in the chat view:
```
Replace in the current file all product names with 
defined key references
```
or:
```
Use the attached documents to create a DITA XML topic, 
add related links in the topic to similar ones, find 
a good place and insert it in the DITA Map
```
Figure 1. Example: Create a new DITA XML topic from a PDF document

or:
```
Add related links in the current topic to similar topics 
from the project
```
Figure 2. Example: Add related links to topic
Agent - Generic agent useful for exploring and making changes to a variety of projects.
Ask - Read-only agent useful to explore, make plans without making actual changes until you switch to one of the other agents.

Each defined agent has a system prompt and references a set of tools which can be used by the LLM. You can define your own agents and have them appear in the Chat view. A general overview of the tools available to these agentic chat modes is available below.

General Overview of Available Tools

AI Positron comes bundled with a variety of tools which are offered to the LLM in order to explore and make changes to content. Here are some of the categories of available tools along with prompt you can test for yourself in the AI Positron chat view:

Tools to explore the overall project. The chat modes have access to:
- A tool which can perform keyword search in the project, for example you can ask it:
```
Find topics about Git Push in the project 
and give me an overview of the most suitable ones.
```
- A tool to grep and perform exact string matches in the project, even by matching inside specifix XML elements. For example:
```
Find places where the Save action is mentioned 
in DITA <uicontrol> elements.
```
- A tool to explore the project folder structure. For example:
```
Where should I save DITA maps in this project?
```
Tools to read content from the current or a different file. Example:
```
Give me suggestions about how to shorten the current document
contents.
```
Tools to make large or small changes to the current or to other documents. Examples:
```
Shorten the title of the current document
```
or:
```
Find and fix logical inconsistencies in the current document
```
Tools to make XML aware changes in documents:
- Apply existing XML refactoring operations on documents. Example:
```
Invoke XML refactor operation to add unique IDs on all pargraphs
```
- Apply XML refactoring using XSLT scripts created by the AI. Example:
```
Invoke XML refactor with custom XSLT to 
replace all <b> elements with <uicontrol>
```
  Figure 3. Example: Use Custom XSLT to Refactor

Tools to call existing AI actions on documents. Example:

Invoke the Proofread AI action on the current 
document content, then save the proposed changes 
to the document

or:

Invoke the improve readability AI action on the current 
document content, then save the proposed changes 
to the document

Add Extra Tools with Model Context Protocol

The Model Context Protocol Preferences page in AI Positron allows you to connect to various MCP servers and allow the LLM to call tools implemented on remote or local servers.

Sample configurations can be found in the Oxygen XML Editor user's manual.

Model Context Protocol gives AI Positron the ability to provide for the LLM close integrations with the issue tracking system or the version control system, for example to allow the LLM to extract the summary and comments made on a GitHub issue and create a draft documentation topic from it. Example prompt:

Obtain description and comments from the DITA OT GitHub issue number 2021 and create a draft documentation 
topic using them

Figure 4. Example: Using MCP to access Atlassian JIRA

Figure 5. Example: Using MCP to access GitHub issues

Conclusion

Obtaining quality output and advice from the LLM, making accurate changes using it is all about the application giving the LLM enough context and allowing it to find extra context if the need arises.

Starting with the use of quality LLMs, combined with a quality created and distilled project context prompt, then continuing with tools that give the LLM access to explore the project and make consistent changes, your short prompts and commands end up being properly interpreted and acted upon.