From 31356eca30c086b37f13e278931b4e30adba96dc Mon Sep 17 00:00:00 2001 From: Radu Coravu Date: Fri, 31 May 2024 15:18:41 +0300 Subject: [PATCH] EXM-54333 Shortenand restructure the AI Positron article. --- topics/ai_positron.dita | 705 +++++++++------------------------------- 1 file changed, 148 insertions(+), 557 deletions(-) diff --git a/topics/ai_positron.dita b/topics/ai_positron.dita index 8bb49dc8..654e9ef0 100644 --- a/topics/ai_positron.dita +++ b/topics/ai_positron.dita @@ -2,10 +2,14 @@ Oxygen AI Positron Assistant Add-on + The Oxygen AI Positron Assistant add-on provides support for helping technical + documentation writers generate and re-write content. It also supports performing AI checks on + multiple files and integrating AI checks with XML technologies like Schematron or + XSLT. Radu Coravu - + @@ -16,572 +20,159 @@ -

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. A setting to switch to using the GPT-4 model is - also provided.

-

More details about installation and all the AI Positron features can be found in the Oxygen User's Manual.

+

This article is intended to be a general overview of the Oxygen AI Positron Assistant + add-on installation, licensing and functionality.

- 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 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 re-structure the content in - various ways.

-

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

-

AI Positron Assistant Samples Playground.

-

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

-

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

-

- The Oxygen Positron Service uses by default the - OpenAI ChatGPT engine version 3.5 API to propose document generation and - change suggestions. -

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

-
-
- Generating and Refining Content -

Once you log in to the server, the following actions for generating content are available - in the Actions drop-down menu at the top of the AI - Positron Assistant side view (and also in the AI Positron - Assistant submenu within the contextual menu, and in the - AI main menu). The progress and results of triggering an action are - displayed in the main - chat pane:

- -
Content Generation
-
-
    -
  • New DITA Topic - Generates a DITA XML - topic based on a text description entered in a popup dialog box.
    • -
  • 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 when editing schemas, XSLT - stylesheets, and Schematron files) - Replaces the selected - instructions with content generated based on them.
    • -
-
- - -
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
-
-

The actions in this category translate the selected text to the target language - (English, German, - French, Japanese), while preserving - the original XML markup.

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

-
- -

-

- Custom actions can be configured in the AI Positron Assistant preferences - page. -

+ Installation and Licensing Overview +
    +
  • Oxygen desktop allows installing two flavors of the add-on:
      +
    • +

      AI Positron Assistant add-on.

      +

      This add-on works through a subscription based model using the Oxygen Positron Service platform which uses in turn the + OpenAI API and functionality.

      +

      Users can create new subscription accounts or authenticate using their existing + Google or Github accounts. The first subscription month is free and + a monthly subscription can be bought in order + to benefit of a number of credits each month.

      +

      You can control from the Preferences page the AI engine to be used by default for + performing actions and for chatting.

      +
      • +
    • +

      AI Positron Assistant Enterprise add-on.

      +

      This add-on allows end users to connect to their own AI engine server. The + following connection types are supported:

        +
      • OpenAI - Connect to your own OpenAI server using your own key. Or connect to + OpenAI-compatible servers like Ollama.
        • +
      • Microsoft Azure Open AI - Connect to an Open AI instance hosted as a virtual + machine on Microsoft Azure.
        • +
      • Anthropic Claude - connect to Anthropic Claude using your own key.
        • +

      +

      From the licensing point of view the AI Positron Assistant Enterprise add-on + works free of charge with any Oxygen XML Editor installation using an + Enterprise license type for Oxygen XML Editor. For all other cases a special license key needs to be purchased + for the add-on to enable this direct access. You can use the Register button in the + AI Positron Assistant side view to configure the special license key.

      +
      • +
    • +
  • Oxygen Web Author also allows installing an AI + Positron Assistant plugin with similar functionality as the one in Oxygen Desktop. + Currently the WebAuthor and Content + Fusion online demo websites come with the AI Positron add-on pre-installed. In + the near future an AI Positron Assistant Enterprise plugin will allow using either + a license server or a special WebAuthor license component to configure a custom AI engine + in the plugin and deliver an on-premise web editing tool inside a company with the AI + Positron Assistant add-on installed.
    • +
-
- 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 - .

-

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

-

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

-

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

    After installing the add-on the following features are available in the Oxygen desktop:

      +
    • AI Positron Assistant side view. This side view + contains the following functionality:
        +
      • Invoke various actions to generate and re-write content using AI.
        • +
      • Chat with the AI.
        • +
      • A History list of previous interactions.
        • +
      • A Favorites drop down list and a way to mark inputs as favorites.
        • +
      • An Attach button to attach images or XML, text resources to the chat + message.
        • +
      • +
    • AI main menu entry with support to invoke actions or to go to the add-ons + preferences page.
      • +
    • AI Positron Assistant contextual menu for all XML documents opened in the + Author visual editing mode.
      • +
    • AI Positron Assistant quick assist actions available on the left vertical + stripe for all XML documents opened in the Author visual editing mode.
      • +
    • AI Positron XML Refactoring actions added to the Project and DITA + Maps Manager views as a way to run actions on multiple files.
      • +
    • 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.
      • +
    • The add-on contributes two XPath extension functions + ai:transform-content and ai:verify-content that can be + used to rephrase content or to perform validation checks on existing content.

    -

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

    -
    - AI Refactoring -

    The AI Positron Assistant add-on contributes an AI - Positron Refactoring action in the contextual menu ( - Refactoring - AI Positron Refactoring - ) of both the Project and DITA Maps - Manager views in .

    -

    You can invoke the AI Positron Refactoring action to apply either a - predefined AI action or a custom prompt to modify the selected resources. The resulting - AI Positron 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. -
    - AI Positron Assistant Preferences Page -

    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 pane 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 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 - - File - New Document - wizard can be used to create a new - AI Positron Custom Actions file that contains a JSON array with - multiple actions. If the actions file is saved in the custom actions folder defined in the - AI Positron Assistant preferences page, validation and content - completion will be automatically provided for it.

    -

    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. -
    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. -
    3. Click Start recording.
      4. -
    4. Open a DITA topic that has a menu cascade without markup (for example: File > - Export).
      5. -
    5. Edit the topic and add markup, transforming it to: - <menucascade> - <uicontrol>File</uicontrol> - <uicontrol>Export</uicontrol> -</menucascade>
      6. -
    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. -
    7. In the resulting dialog box, save the final result as either a Positron action or as a - favorite chat prompt.
      8. -

    +
    + Predefined and Custom Actions +

    Once you log in to the server, a set of predefined actions are available, grouped in + categories: Accessibility, Content Generation, , Development, + Rewrite, Overview, Marketing and Translation. The AI Positron Assistant Samples Playground samples + project contains useful samples to test the functionality of these actions.

    +

    Custom actions can also be created and used. The + same AI Positron Assistant Samples Playground contains + some sample custom actions. Some usage examples can be found in the samples playground.

    -
    - 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, content)
    -
    -

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

    -

    The function has two string parameters:

      -
    • instruction - The OpenAI instruction to - be performed on the content.
      • -
    • 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, 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.
      • -
    • 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>

    -
    -     -
    -

    +
    + Batch Processing +

    The AI Positron Refactoring actions added to the + Project and DITA Maps Manager views are a way to run actions on multiple + files. 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.

    +

    In addition XML Refactoring actions based on XSLT or XQuery can use the XPath + extension functions added by the add-on to perform batch changes in XML documents. Some + examples can be found in the samples playground.

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

    +
    + Useful Links +
      +
    • AI Positron Assistant Samples Playground.
      • +
    • + Blog Post About AI Positron Add-on By Tom + Johnson
      • +
    • + Webinar: AI as a Tool for Technical Content Creation +
      • +
    • + Webinar: Leveraging the Power of AI and Schematron for + Content Verification and Correction
      • +
    - - - AI Positron Assistant Samples Playground - - - Blog Post About AI Positron Add-on By Tom Johnson - - - Webinar: AI as a Tool for Technical Content Creation - - - Webinar: Leveraging the Power of AI and Schematron for Content Verification and - Correction - - +