Edit online

Oxygen AI Positron Assistant

The Oxygen AI Positron Assistant add-on uses the advanced Oxygen AI Positron service to support technical documentation writers throughout their content creation process.

Overview

In a 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 AI services (such as 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 re-structure the content in various ways.

Note: Content received from the OpenAI ChatGPT model may be inaccurate or contain misleading information, so it needs to be thoroughly reviewed and revised accordingly.
Terms: The terms of use for the service can be found here.

AI Positron Assistant Samples Playground.

Quick Installation

You can drag the following Install button and drop it into the main editor in Oxygen to quickly initiate the installation process:

Install

Manual Installation

To manually install this add-on, follow this procedure:
  1. Go to Help > Install new add-ons to open an add-on selection dialog box. Enter or paste https://www.oxygenxml.com/InstData/Addons/default/updateSite.xml in the Show add-ons from field or select it from the drop-down menu.
    Note: If you have issues connecting to the default update site, you can download the add-on package, unzip it, then use the Browse for local files action in the Install new add-ons dialog box to locate the downloaded addon.xml file.
  2. Select the Oxygen AI Positron Assistant add-on and click Next.
    Important: There are two different iterations of the add-on and you can only have one or the other installed at once:
    • Oxygen AI Positron Assistant - The regular version of the add-on.
    • Oxygen AI Positron Assistant (Enterprise) - This Enterprise version is for those who want to connect to their own OpenAI or MS Azure OpenAI account.
  3. Read the end-user license agreement. Then select the I accept all terms of the end-user license agreement option and click Finish.
  4. Restart the application.

Result: The AI Positron Assistant side view is 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.

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).

Note: By default, the Oxygen Positron Service uses the OpenAI ChatGPT server version 3.5 API to propose document generation and change suggestions. The used model can be changed to a more advanced model (for example, GPT 4) in the AI Service Configuration Preferences Page.

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.

Important: To use your own company-specific AI service, the specific Oxygen AI Positron Assistant Enterprise add-on needs to be installed instead of the one listed above.

Accessing AI-Powered Actions

Once you log in to the server, a variety of AI actions are available in:
  • The Actions drop-down menu at the top of the AI Positron Assistant side view.
  • The main chat panel when a conversation has not yet started.
  • The AI Positron Assistant submenu that is available in the contextual menu when right-clicking in the main editor.
  • The AI main menu at the top of the application.

In addition, when moving the cursor within the document, a quick assist bulb () appears in the navigation vertical stripe bar. Clicking the bulb opens a popup with actions such as Correct Grammar, Improve Readability, or Use Active Voice that are invoked in the context of the closest paragraph that contains the cursor.

The progress and results of triggering an action are displayed in the main chat pane.

Built-in AI Actions

Accessibility
  • Generate Image Alternate Text - Generates an alternate text for a DITA XML image that is selected in the main editing area in the Author visual editing mode.
Content Generation
  • Generate Documentation Draft - Generates a documentation draft of a DITA XML topic based on a configuration file that fine tunes the generation process by specifying the context, audience, summary, instructions, images, and a similar topic to help the AI generate the draft content.
  • New DITA Topic - Generates a DITA XML topic based on a text description entered in a popup dialog box.
  • Update Content Based on Images - Updates the content of a DITA XML topic based on the images that it references.
  • Continue Writing - Generates additional text based on the content preceding the cursor position.
  • 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 approximate 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).

  • Follow Instructions (available for XSLT, Schematron, XSD, CSS, XQuery, JSON, and JSON Schema) - Replaces the selected instructions with content generated based on them.
Development
  • Explain Code (available for XSLT, Schematron, XSD, CSS, XQuery, JSON, and JSON Schema) - Generates an explanation of the code found in the current selection or the code at the current cursor location (or the whole document).
  • Chat About Code (available for XSLT, Schematron, XSD, CSS, XQuery, JSON, and JSON Schema) - Creates a new chat to start a discussion with the AI regarding the code found in the current selection or the code at the current cursor location (or the whole document).
  • Document Code (available for XSLT, XSD, and Schematron) - Generates the documentation for the selected content, current node, or entire document. It inserts the documentation as an XML comment before the documented code.
  • Generate Code (available for XSLT, Schematron, XSD, CSS, XQuery, JSON, and JSON Schema) - Generates the code for the current editor type (text/xsl, text/xquery, text/css, text/json, text/xsd, text/sch) based on the instruction specified in the selected text from the editor or in the comment preceding the cursor location.
Rewrite
  • Correct Grammar - Generates a suggestion for correcting the grammar and spelling within the selected content.
  • Improve Readability - Modifies the selected content to improve readability and fix grammar/spelling errors. If you hover the mouse prompt over this button, a Settings button becomes available in the top-right corner. Clicking the Settings button opens a pop-up window where you can choose the writing level of the content to be generated. You can choose between: 5th grade (Very Easy), 8th grade (Plain English), and College (Advanced).
  • Use Active Voice - Generates a suggestion for replacing the selected content with content that has been converted from passive to active voice.
  • 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.
Overview
  • Answer Questions - Generates answers to questions that the AI finds within 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).
  • Summarize - Generates a summary of the selected content (or the entire document if there is no selection).
  • Readability - Generates suggestions for changing the selected content (or the entire document if there is no selection) to improve its general readability.
Translation
  • English, French, German, Japanese - These actions translate the selected text to the target language, while preserving the original XML markup.
  • Other... - This action behaves like the previous ones, but it allows you to provide the target language. You can either choose from the predefined values or type another one.
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 ideas or release notes.
  • Improve SEO - Rewrites the content to enhance search engine optimization.
  • 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.
Tip: Custom actions can be configured in the AI Positron Assistant preferences page.

AI Positron Assistant View

The add-on provides access to the AI Positron Assistant side-view. If the view is not displayed, it can be opened by selecting it from Window > Show View.

Figure 1. AI Positron Assistant View

The Actions drop-down menu at the top of the AI Positron Assistant view contains the available AI-powered actions that can be used to generate and refine content. Simply select the action to trigger it. You can hover the mouse cursor over an action to see a description of what the action does. A set of 5 recently used actions are also available in the Actions drop-down menu.

The Record button in the top-left corner of the view allows you to create custom actions or prompts by recording changes.

There is also a user drop-down menu at the top-right corner of the AI Positron Assistant view that contains the following:
  • My account - Opens a webpage where you can see your current subscription package and credit status.
  • 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.

The main chat pane presents the 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 chat pane displays the progress and results.

You can also start chatting directly, without invoking an action. In this case, if there is content selected in the main editor area when a chat is initiated, the selection is passed to the AI as context for the conversation.

The response is received from the server in streaming mode (the AI sends chunks of the response as it is being generated rather than waiting to send the entire response after it is generated).
Note: When working with Oxygen XML Editor versions 27 and newer, after the entire response is received, if it contains well-formed XML content and the current document is in the Author visual editing mode, the response is presented in a visual manner by default, without showing the XML tags. A small toggle button located in the response area allows you to choose between visual or plain XML text for the presentation of the response.
Once the entire response is received from the server, the following actions are available under the response:
  • 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.
Tip: You can also partially select content from the response area, then right-click to open the contextual menu, and use the Insert/Replace, Preview, or Copy actions on that partially selected content.

The Chat History drop-down toolbar button makes it easy to go back to previous conversations and continue them.

You can use the bottom pane to refine the response by sending a message to the AI platform and it will generate a new response based upon your message. You can create your own favorite prompts and use supported variables to specify the content that is sent to the platform. You can use the Favorites drop-down button to store a favorite prompt. You can use the Insert Variables drop-down button to select one of the supported variables:
  • ${selection} - Expands to the currently selected content.
  • ${selection-original} - Expands to the currently selected content. If the current selected content contains track changes, they are rejected, resulting in the original version of the text.
  • ${selection-final} - Expands to the currently selected content. If the current selected content contains track changes, they are accepted, resulting in the final version of the text.
  • ${document} - Expands to the content of the entire document.
  • ${attach(filePath)} - Attaches a specified image (in png or jpeg format) or an XML or text file to the conversation. You can also attach files in an easier way by using the dedicated Attach action.
Tip: Previously sent prompts can be modified directly in the chat thread. Once a prompt is edited, a new chat thread is started based on the new prompt's content. For edited prompts, you can use the Next/Previous buttons to navigate between chat threads.

To clear the information in the chat pane and start a new chat, click the New Chat button in the top-right corner of the view.

Generating Documentation Drafts

The AI Positron Assistant add-on provides the ability to generate a documentation draft of a DITA topic based on a configuration file that tailors the draft generation process using a context, instructions, images, and other data.

Once the add-on is installed, you can use the New Document wizard to create a new AI Doc Draft Configuration file, that can be edited in Author mode. Validation and content completion are automatically provided for such configuration files. The Author mode also renders short explanations for each element, as well as buttons for inserting the optional elements.

After providing the configuration data, you can use the Generate Documentation Draft action to trigger the AI-based drafting process. Once the AI response is complete in the AI Positron Assistant side-view, click the Create document link to create a new DITA topic with content generated based upon the data in the configuration file.

Notice: Only PNG, JPEG, and non-animated GIF images should be provided in the configuration file.
The simplest form of the configuration file would only contain the title and summary that will be used by the AI as a starting point:
<?xml version="1.0" encoding="UTF-8"?>
<doc-draft>
  <title>Generate Documentation Draft</title>
  <instructions>
    <draft-summary>The new "Generate Documentation Draft" action was added to the 
"Content Generation" category and can be used to draft a DITA documentation topic
using AI and a configuration file.</draft-summary>
  </instructions>
</doc-draft>
Other data elements can be used to further configure the drafting process, such as the context, target audience, instructions, images, and a similar topic.
<?xml version="1.0" encoding="UTF-8"?>
<doc-draft>
  <title>Generate Documentation Draft</title>
  <context>I am working on the user manual of a software application called Oxygen XML Editor,
 used for authoring and publishing XML content.</context>
  <prolog>
    <metadata>
      <audience>The audience of our user manual is very wide and includes 
people without a technical background.</audience>
    </metadata>
  </prolog>
  <instructions>
    <draft-summary>We have a new action in the contextual menu of the Project side-view,
 called "Format and Indent...",
 that can be used to pretty print multiple files at once. The action is available in both 
the Oxygen XML Editor stand-alone distribution and the Eclipse plug-in.</draft-summary>
    <instruction>Analyze the following image and document the dialog box
 and all its components.</instruction>
    <image href="format-and-indent-files.png"/>
    <instruction>Also add a DITA "note" element that mentions the fact that this feature 
is not available for XQuery files.</instruction>
  </instructions>
  <relationship-context>
    <similar-topic href="spell-check-in-files.dita"/>
  </relationship-context>
</doc-draft>

AI Refactoring

The AI Positron Assistant add-on contributes an AI Positron XML Refactoring action in the contextual menu (Refactoring > AI Positron XML Refactoring) of both the Project and DITA Maps Manager views in Oxygen XML Editor. It can be used to refactor multiple XML files (local or remote) at once.

You can invoke the AI Positron XML Refactoring action to apply either a predefined AI action or a custom prompt to modify the selected XML resources. The resulting AI Positron XML Refactoring dialog box presents an estimate of the amount of credits that will be consumed by the operation, and you have the option to preview the changes before applying them over the original content.

For example, you could use the predefined Translate to action to translate multiple DITA topics into a certain language or apply the Correct Grammar or Improve Readability actions on multiple resources.

XML Refactoring

The add-on contributes AI-specific XML refactoring actions in the XML Refactoring tool's wizard (Tools > XML Refactoring, in the AI category):
  • Generate alternate text for images in DITA XML topics - Generates an alternate text for images in DITA XML topics.
  • Generate missing short descriptions in DITA XML topics - Generates a short description (inside a <shortdesc> element) for DITA XML topics.
  • Shorten existing short descriptions in DITA XML topics - Generates a shorter version of an existing short description for DITA XML topics.
The XML refactoring actions can be applied on multiple resources and are based on the ai:transform-content and ai:verify-content XPath extension functions contributed by the add-on.

Oxygen AI Positron Assistant Preferences Page

Various settings can be configured in Options > Preferences > Plugins > Oxygen AI Positron Assistant:
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.
Actions section
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.
Actions to exclude
You can specify a comma-separated list of IDs for the actions that you do not want presented in the list of available actions. Use the menu to the right of the text field to choose the actions to exclude.
XPath Functions section
Enable XPath Functions
Enables the use of AI-specific XPath functions in Oxygen XML Editor 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.

AI Service Configuration Preferences Page

Various service-related connection settings can be configured in Options > Preferences > Plugins > Oxygen AI Positron Assistant > AI Service Configuration:
AI Positron Service address
Currently, there is only one public platform that provides this service.
Default model
The default model is used for the chat pane and for actions that do not explicitly specify a fixed model. Each chosen model consumes a certain number of credits per token.

Validation Quick Fixes

When validation problems are displayed in the Results pane, you can right-click on 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 chat pane (within the AI Positron Assistant 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 a folder that contains custom actions.

Once the add-on is installed, the New Document wizard can be used to create either a new AI Positron Custom Action file that contains a custom action definition in JSON format or an AI Positron Custom Actions List that contains a JSON array with multiple defined actions. Validation and content completion are automatically provided for such custom action files. If the action definition files are saved in the custom actions folder defined in the AI Positron Assistant preferences page, the AI Positron Assistant view should automatically reload its Actions drop-down list to include them.

The most simple action defines an action id, title, type, and context:
{
    "id": "my.action.id",
    "title": "Improve Grammar",
    "type": "replace-selection-with-fragment",
    "input-type": "markup",
    "context": "Improve grammar in the following content preserving the XML markup:"
}
Defined actions can contain expandable parameters and their values can be customized before invoking the action:
{
   "id": "my.action.id",
   "title": "Improve Grammar",
   "type": "replace-selection-with-fragment",
   "input-type": "markup",
   "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 as either a Positron action or as a favorite chat prompt.

For example, if you want to add DITA markup to menu cascades, you can follow these steps:
  1. Click the Record button.
  2. In the Record examples for instructions dialog box, enter some instructions like: You are a technical writer. Add DITA markup to menu cascades.
  3. Click Start recording.
  4. Open a DITA topic that has a menu cascade without markup (for example: File > Export).
  5. Edit the topic and add markup, transforming it to:
    <menucascade>
      <uicontrol>File</uicontrol>
      <uicontrol>Export</uicontrol>
    </menucascade>
  6. 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:
    
  7. In the resulting dialog box, save the final result as either a Positron action or as a favorite chat prompt.

Custom Validation Rules

The add-on contributes two XPath extension functions (available in the content completion proposals for Schematron, XSLT, XQuery, and XPath) that can be used to rephrase content or to perform validation checks on existing content:

ai:transform-content(instruction, (user, agent,)* content)

Use this function from namespace http://www.oxygenxml.com/ai/function to automatically transform content using AI.

The function has the string parameters:
  • instruction - The OpenAI instruction to be performed on the content.
  • user, agent - You can add multiple pairs of user-agent data that will be passed to the AI as the history of the conversation.
  • content - The content to be transformed.

It returns a string that represents the transformed content.

Here is an example of a custom Schematron schema that uses the transform-content function to correct the number of words used in a short description:
<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+')) > 50" sqf:fix="rephrase">
      The phrase must contain less than 50 words.</sch:report>
            <sqf:fix id="rephrase">
                <sqf:description>
                    <sqf:title>Rephrase phrase to be less that 50 words</sqf:title>
                </sqf:description>
                <sqf:replace match="text()" select="ai:transform-content(
                'Reformulate phrase to be less that 50 words', .)"></sqf:replace>
            </sqf:fix>
        </sch:rule>
    </sch:pattern>
</sch:schema> 
ai:verify-content(instruction, (user, agent,)* content)

Use this function from namespace http://www.oxygenxml.com/ai/function to automatically validate content using AI.

The function has two string parameters:
  • instruction - The OpenAI instruction to be performed on the content.
  • user, agent - You can add multiple pairs of user-agent data that will be passed to the AI as the history of the conversation.
  • content - The content to be validated.

It returns a boolean value that represents the result of the validation.

Here is an example of a custom Schematron schema that uses the verify-content function to check a short description for instances of a passive voice:
<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="ai:verify-content('Does the following content has passive voice?', .)"
            sqf:fix="rephrase">The phrase uses passive voice.</sch:report>
      <sqf:fix id="rephrase">
         <sqf:description><sqf:title>Rephrase text to be active voice</sqf:title>
</sqf:description>
         <sqf:replace match="text()"
                select="ai:transform-content('Rephrase text to be active voice', .)"/>
         </sqf:fix>
      </sch:rule>
  </sch:pattern>
</sch:schema> 

Resources

To see a visual demonstration of the AI Positron Assistant add-on, along with various uses cases for using the tool, see the following recorded webinar: AI as a Tool for Technical Content Creation.

See ways to use AI tools from XSLT stylesheets and Schematron schemas in the following recorded webinar: Leveraging the Power of AI and Schematron for Content Verification and Correction.