Oxygen AI Positron Assistant Add-on
We are proud to introduce our new Oxygen AI Positron Assistant add-on, which provides support for helping technical documentation writers generate and re-write content by using the Oxygen AI Positron service.
The Oxygen Positron Service
uses the OpenAI ChatGPT
model GPT-3.5
to provide document generation, change suggestions, and
translation capabilities.
More details about installation and all the AI Positron features can be found in the Oxygen User's Manual.
Overview
In simplified form, technical documentation is often done in two stages: analysis and implementation. In the analysis stage, technical writers could use various resources such as web searches, ChatGPT, or discussions with colleagues or engineers to further understand the subject that needs to be documented.
In the second stage, technical writers would use tools such as Oxygen XML Editor to write the actual content. The Oxygen AI Positron Assistant add-on provides various ways to use ChatGPT to help writers while editing or reviewing the technical documentation. For example, it can be used to receive hints about what to write next, improve the readability of content, or restructure the content in various ways.
As always, we are interested in your feedback and improvement suggestions.
Manual Installation
- Go to Show add-ons from field or select it from the drop-down menu. to open an add-on selection dialog box. Enter or paste https://www.oxygenxml.com/InstData/Addons/default/updateSite.xml in the
- Select the Oxygen AI Positron Assistant add-on and click Next.
- Read the end-user license agreement. Then select the I accept all terms of the end-user license agreement option and click Finish.
- Restart the application.
Result: The AI Positron Assistant and AI Positron Chat side views are now available.
Connecting to the Oxygen AI Positron Service
You can use the AI Positron Assistant side view
to easily configure login details and connect to the Oxygen Positron
Service
in the web browser. The service is free to use for up to 250 requests per
month.
To initiate the connection process, use the Connect button in the AI Positron Assistant view (or from the user drop-down menu at the top-right corner of the view).
AI Server Requests and Credits
Each user has a limit to the number of requests that are sent to the AI server each month and this is managed through the use of credits. Each user has a default limit of 100,000 credits per month.
- 1 token of GPT_3_5_4K = 1 credit
- 1 token of GPT_3_5_16K = 2 credits
- 1 token of GPT_4_8K = 30 credits
- 1 token of GPT_4_32K = 60 creditsNote: The transitions from GPT_3_5_4K to GPT_3_5_16K and from GPT_4_8K to GPT_4_32K are done dynamically by the AI Positron depending on the length of the input text.
Each invoked action consumes tokens with the AI prompt associated with the action, the input text (editor text, selection from the editor text, chat messages, or user input), and the AI response. After these, the tokens are converted to credits according to the used model.
Generating and Refining Content
- Content Generation
-
-
Continue Writing - Generates additional text based on the content to the left of the cursor.
- Follow Instructions (available when editing schemas, XSLT stylesheets, and Schematron files) - Replaces the selected instructions with content generated based on them.
-
- DITA Topic Tools
-
-
Improve Readability - Generates a modification to the selected content to improve readability and correct grammar/spelling problems, while preserving the original XML markup.
-
Generate Topic - Generates a DITA XML topic based on a text description entered in a popup dialog box.
-
Short Description - Generates a short description ( inside a
<shortdesc>
element) based on a summary of the selected text (or the entire document if there is no selection). You can configure the style and the approximative number of sentences to be generated. -
Index Terms - Generates a
<keywords>
element that contains index terms obtained from the selected text (or the entire document if there is no selection).
-
- Translation
-
The actions in this category translate the selected text to the target language (English, German, French, and Japanese), while preserving the original XML markup.
- Overview
-
- Readability - Generates suggestions for changing the selected content (or the entire document if there is no selection) to improve its general readability.
-
Summarize - Generates a summary of the selected content (or the entire document if there is no selection).
- Generate Questions - Generates a list of five questions that are answered within the selected content (or the entire document if there is no selection).
-
Answer Questions - Generates answers to questions that the AI finds within the selected content (or the entire document if there is no selection).
- Rewrite
-
-
Itemize - Generates a suggestion for converting the selected content into a list of items.
- Join Items - Generates a suggestion for converting the selected list of items into a paragraph.
- Use Active Voice - Generates a suggestion for replacing the selected content with content that has been converted from passive to active voice.
- Correct Grammar - Generates a suggestion for correcting or enhancing grammar and spelling within the selected content.
-
- Marketing
-
- Release Notes - Creates release notes based on a set of features or issue ticket numbers with optional descriptions.
- Marketing Post - Creates a marketing post based on a list of release notes.
- Pain-Agitate-Solution - Rewrites the content using a marketing style based on the Pain-Agitate-Solution framework.
- Features-Advantages-Benefits - Rewrites the content using a marketing style based on the Features-Advantages-Benefits framework.
Custom actions can be configured in the AI Positron Assistant Preferences Page.
AI Positron Views
The add-on provides access to the following side-views: AI Positron Assistant and AI Positron Chat. If a view is not displayed, it can be opened by selecting it from .

AI Positron Assistant View
The AI Positron Assistant view contains the available actions (buttons) that can be used to generate and refine content. Simply click a button to trigger the corresponding action. You can hover the mouse cursor over a button to see a description of what the action does.
The Record button in the top-left corner of the view
allows you to create custom actions or prompts by
recording changes.
- Usage status - Opens a dialog box that displays your usage information.
- Disconnect - Disconnects Oxygen from
the
Oxygen Positron Service
. - Preferences - Opens the Oxygen AI Positron Assistant preferences page where you can configure the AI Positron service address and provide a Context for the user that the AI will use to create more relevant and personalized responses.
AI Positron Chat View
The AI Positron Chat view presents results after processing an action and allows you to further refine the responses by sending messages to the Positron service platform. When an AI Positron action is triggered, the AI Positron Chat view is automatically opened and the progress and results are displayed in the top pane within the view.
- Insert/Replace - Inserts the response at the cursor location within the document (or replaces the selected content).
- Preview - Allows you to preview the content that would be inserted at the cursor location within the document.
- Copy - Copies the response to the system clipboard.
The Chat History drop-down toolbar button makes it easy to go back to previous conversations and continue them.


- ${selection} - Expands to the currently selected content.
- ${document} - Expands to the content of the entire document.


To clear the information in the AI Positron Chat
view and start a new chat, click the New Chat button in the top-right corner of the
view.
AI Positron Assistant Preferences Page
- AI Positron Service address
- Currently, there is only one public platform providing this service.
- Default model
- The default model is used for the chat view and for actions that do not explicitly specify a fixed model. Each chosen model consumes a certain number of credits per token.
- Context
- The context provides useful information about the user to the AI and is used in each action and chat request to create more relevant and personalized responses.
- Load default actions
- Specifies if default actions are loaded.
- Additional actions folder
- You can use this option to specify a local folder where you have stored additional actions.
- Enable XPath Functions
- Enables the use of AI-specific XPath functions in the application when applying
Schematron validation or XSLT transformations. This feature is disabled by default.
- Cache responses and reuse them for identical prompts
- If enabled (default), responses for identical requests are stored (cached), resulting in fewer requests being sent to the AI server and faster completion times. A Clear cache button located to the right of this option can be used to clear the cache.
- Cache size
- Specifies a maximum limit for the cache size.
- Notify me when the number of requests exceeds
- You can select this option and specify a number of AI requests that when exceeded, a confirmation dialog box is displayed asking if you want to continue using the XPath AI functions. If you select "No" for the answer, the XPath functions will be disabled.
Validation Quick Fixes
When validation problems are displayed in the Results pane, you can right-click a problem and use the AI Positron Fix action to ask the AI Positron platform for help with fixing the problem. It will propose content in the AI Positron Chat view that can be used to solve the problem.
Creating Custom Actions
In the AI Positron Assistant Preferences Page you can define a reference to the folder containing custom actions.
Once the add-on is installed, the AI Positron Custom Actions file containing a JSON array with multiple actions. If the actions file is saved in the custom actions folder defined in the preferences, validation and content completion will be automatically provided for it.
dialog wizard can be used to create a new[ { "id": "my.action.id", "title": "Improve Grammar", "type": "replace-selection-with-fragment", "context": "Improve grammar in the following content preserving the XML markup:" } ]
[ { "id": "my.action.id", "title": "Improve Grammar", "type": "replace-selection-with-fragment", "context": "${style} Improve grammar in the following content preserving the XML markup:", "expand-params":[ { "name": "style", "label": "Style", "value": "", "alternate-values": ["Use active voice.", "Use passive voice."], "alternate-value-labels": ["Active voice", "Passive voice"], "choice-type": "single-choice" } ] } ]
Create Custom Prompts/Actions by Recording Changes
The Record button in the top-left corner of the view allows you to create new AI
actions. It opens the Record examples for instructions dialog box
where you can provide a set of instructions that are intended for the AI to follow. Then,
after clicking the Start recording button at the bottom of the dialog
box, you can record a collection of examples in the editing area that will help the AI
better follow the given instructions. The examples are recorded from the changes made in the
open editors.
After providing examples, you need to click the Record button
again to stop the recording. You will then have the opportunity to save the final result
either as a Positron action or as a favorite chat prompt for the AI Positron Chat
View.
- Click the
Record button.
- In the Record examples for instructions dialog box, enter some instructions like: You are a technical writer. Add DITA markup to menu cascades.
- Click Start recording.
- Open a DITA topic that has a menu cascade without markup (for example:
File > Export
). - Edit the topic and add markup, transforming it to:
<menucascade> <uicontrol>File</uicontrol> <uicontrol>Export</uicontrol> </menucascade>
- Click the
Record button again to stop the recording. The system generates the following instructions with examples:
You are a technical writer. Add DITA markup to a menu cascades. ### Input: <p>File > Export</p> Output: <p><menucascade><uicontrol>File</uicontrol> <uicontrol>Export</uicontrol></menucascade></p> Input: ${selection} Output:
Custom Schematron Validation Rules
The add-on contributes two XPath extension functions:
ai:transform-content(instruction, content)
and
ai:verify-content(instruction, content)
, which can be used from custom
Schematron schemas to rephrase content or to perform validation checks on existing
content.
<sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron" queryBinding="xslt3" xmlns:sqf="http://www.schematron-quickfix.com/validator/process"> <sch:ns uri="http://www.oxygenxml.com/ai/function" prefix="ai"/> <sch:pattern> <sch:rule context="shortdesc"> <sch:report test="count(tokenize(.,'\s+')) > 10" sqf:fix="rephrase"> The phrase must contain less than 10 words.</sch:report> <sqf:fix id="rephrase"> <sqf:description> <sqf:title>Rephrase phrase to be less that 10 words</sqf:title> </sqf:description> <sqf:replace match="text()" select="ai:transform-content( 'Reformulate phrase to be less that 10 words', .)"></sqf:replace> </sqf:fix> </sch:rule> </sch:pattern> </sch:schema>
XML Refactor
The two XPath extension functions contributed by the add-on:
ai:transform-content(instruction, content)
and
ai:verify-content(instruction, content)
can also be used with an XML refactor action.
Here is an example of a custom XML refactor action that can be used to rephrase a short description so that it contains less words:
https://github.com/oxygenxml/dita-refactoring-examples/tree/master/45%20AI%20Refactor
Future Improvement Ideas
- Support for converting between various text formats such as Markdown or ASCIIDoc to DITA XML.
- Support for automatically changing the content based on comments left by reviewers.
- More actions for changing the tone of voice (active/passive/marketing) for existing content.