Oxygen AI Positron Assistant Add-on

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.
2. Select the Oxygen AI Positron Assistant add-on and click Next.
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.

Credits are calculated using a weighted model based on tokens:

• 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 credits
  Note: 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.

Once you log in to the server, you can generate content using the AI Positron Assistant side view, which is available in the AI main menu and the AI Positron Assistant submenu within the contextual menu. The progress and results of triggering an action are displayed in the AI Positron Chat view:

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.

There is also a user drop-down menu at the top-right corner of the AI Positron Assistant view that contains the following actions:

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

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). Once the entire response is received from the server, the following actions are available in the AI Positron Chat view (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.

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.
• ${document} - Expands to the content of the entire document.

Various settings can be configured in Options > Preferences > Plugins > Oxygen AI Positron Assistant:

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.

The simplest action defines an action id, title, type and context:

[
    {
        "id": "my.action.id",
        "title": "Improve Grammar",
        "type": "replace-selection-with-fragment",
        "context": "Improve grammar in the following content preserving the XML markup:"
    }
]

Defined actions can contain expandable parameters for which values can be customized before invoking the action:

[
    {
        "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"
        }
     ]
    }
]

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:
   

Here is an example of a custom Schematron schema that can be used to rephrase a short description so that it contains less words:

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

Here's a list of possible future ideas for using AI to improve the technical documentation processes:

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