Edit online

Oxygen AI Positron Assistant Add-on

15 Apr 2023
Read time: 27 minute(s)

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.

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.

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.

As always, we are interested in your feedback and improvement suggestions.

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

Result: The AI Positron Assistant, AI Positron Chat and AI Positron Activity 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).

Generating and Refining Content

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

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

AI Positron Chat View

The AI Positron Chat side-view presents results after processing an action and allows you to further refine the responses by sending messages to the Positron service platform.

Figure 1. AI Positron Assistant and AI Positron Chat Views

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.

Once a 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 system clipboard.
You can use the bottom pane to send a message to the AI platform and 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.

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 Activity Side View

The AI Positron Activity side view displays results for various reports and information about each executed action. To open the view, click on the Show Activity History button in the top-right corner of the AI Positron Chat view.

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.

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.

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> 

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

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.