AI in technical writing: reinvent your work with StackSpot

Artificial Intelligence (AI) is advancing rapidly and reshaping the way we work in the tech industry. This article explores AI in technical writing, with insights from HubSpot’s blog article “How AI Works,” which notes that AI excels at handling repetitive tasks, freeing people to engage in more creative activities.

For technical writers, AI holds the promise of transforming how documentation is created, delivered and managed. AI tools are essential for boosting productivity through tasks like grammar correction, multilingual translation, and text review.

This article illustrates how Quick Commands and AI Agents in StackSpot AI are powerful tools to translate and review documentation. Read on to learn more about AI in technical writing.

What is StackSpot AI? 

StackSpot AI is an AI assistant designed to enhance code quality and streamline workflows. Create a StackSpot AI account to simplify daily tasks and improve efficiency through its chat interface or IDE extension.

> Please refer to the documentation for more information on downloading the extension and other platform features.

Using StackSpot AI

StackSpot AI offers language translation from English into Portuguese through its Quick Commands feature.

Quick Commands are predefined instructions that guide a large language model (LLM) in specific actions. They provide fast and efficient ways to give context to the LLM. They are user-friendly and accessible via right-click or by typing “/.” directly into the chat.

Here are some usage examples:

Case 1: Quick Commands for Translations

Issue: Our documentation was initially in English and needed to be quickly translated into Portuguese to broaden our product’s reach.

Solution: We created a Quick Command IDE and a prompt to translate English pages into Portuguese. Here’s a summary of the steps we followed in the StackSpot AI Portal:

1. Visit the StackSpot AI Portal and create an account. Then, navigate to the Quick Command section to set one up;
2. Select the IDE option (as we treat documentation as code and work within the concept of IDEs/repositories);
3. Enter a name and the command that will appear in your IDE, and describe its purpose;
4. Choose the prompt option and detail the action you want the command to perform;
5. You can incorporate Knowledge Sources —chunks of information serving as a knowledge base— to preserve your text’s tone, voice, and style. Adding more relevant information can enhance your StackSpot AI experience.

Using the Command: 

To use the command, navigate to your project in the IDE, select the document to translate, and either right-click or type “/” in the chat. Next, select StackSpot AI > My Quick Commands > Your Command Name.

Outcome: 

The translation quality was excellent—faster and more accurate than standard translators. The Knowledge Source also helped fine-tune the text’s tone to match our preferences.

After running the command, we still needed to review the content and refine some wording to enhance the quality and flow of the sentences. Nevertheless, this process enabled us to complete the entire documentation in Portuguese faster than expected.

• See our StackSpot AI documentation.

Case 2: Quick Commands for reviewing text accessibility 

Ensuring that your content is accessible to all users is essential. We faced the challenge of improving the accessibility of our documents, and StackSpot AI proved to be a valuable ally throughout this process. Here are the steps we took to make progress:

• We created another Quick Command IDE, following the same steps outlined earlier.
• The goal was to assist the documentation team in verifying text accessibility, including ensuring that images have proper alternative descriptions.
• We refined the prompt multiple times to achieve the desired result.

The Knowledge Source feature was key, providing additional insights into the Web Content Accessibility Guidelines (WCAG), resulting in more accurate responses. Using the command, StackSpot AI delivered the result in the IDE chat, with the following guidelines:

1. Buttons and actions
Add contextual descriptions for the buttons. 

Before: 
**Step 2.** Enter your email and click **Continue**;

**Step 3.** Enter your password and click **Login**;

After:
**Step 2.** Enter your email and click the **Continue** button to proceed;

**Step 3.** Enter your password and click the **Login** button to access your account;


Before: **Step 4:** Click on **'Export CSV'** to download the file.

After: **Step 4:** Click on **'Export CSV'** to download the file in .csv format.

2. Describe links

Update the link text to something more concise and explanatory.

Before: 
**Step 1:** [**Log in'**](link) to your StackSpot account and click on 'Manage Account';

After:
**Step 1:** [**Log in to your StackSpot account and click on 'Manage Account'to manage and download the event history**](link);

3. Images descriptions
- Excessive Detail: The description includes unnecessary details, such as "the mouse clicks," which can be simplified for better readability.
- Lack of Context: It doesn't explain the purpose of the action (e.g., why the user is selecting dates or exporting the file).
- Verbosity: The text is slightly verbose, making it harder for screen reader users to process.
- Present Tense: Using present tense is generally better for alt text, as it improves the flow and clarity for screen readers.

Before:
![GIF showing the StackSpot EDP portal screen in the Event History section. The mouse clicks on the Start Date field and selects a date from the appearing calendar. Then, the mouse clicks on the End Date field and chooses a date from the calendar. Finally, the mouse clicks the Export CSV button to export the event history data.](gif)

After:
![GIF of the StackSpot EDP portal in the Event History section. A user selects a start and end date from the calendar and clicks the Export CSV button to download the event history data.](gif)

We are improving accessibility by enhancing alternative texts for images, refining heading structures, and clarifying link descriptions. Additionally, we are upgrading the command to provide more accessible documentation.

Case 3. Agents

StackSpot AI has introduced a new feature: specialized Agents. These AI Agents are fully customizable and can assist with tasks ranging from code generation and quality control to creating and improving documentation.

The Tech Writing team created an Accessibility Verification Agent to check whether a file is more accessible than earlier versions. It identifies improvements in language quality and document structure while providing more accurate alternative texts.

Here are the steps we followed to create an Agent:

1. Log in to the StackSpot AI Portal;
2. Click on the ‘Agents’ section;
3. Click on ‘Create Agent’ and complete the required fields:
   • Name: Check Accessibility
   • System Prompt: Enter all the instructions and information needed for the Agent to provide the desired output. Define the tone and model it should follow. See the example:

You are a technical writer specializing in content accessibility and have deep knowledge of the WCAG (Web Content Accessibility Guidelines). Your main responsibility is to review and ensure that texts, both in Portuguese and English, comply with accessibility standards. For each selected text, you must identify and correct accessibility issues, such as color contrast, readability, proper structuring, clear and objective language, and other aspects that may impact the reading experience of people with disabilities. You aim to make texts more inclusive and accessible, following the WCAG guidelines.

3. Suggested Commands: This field includes pre-established phrases or questions to facilitate interaction with your Agent.
   Example: Review this text and correct it with a focus on accessibility.
4. Conversational Mode: This option allows multiple message exchanges between the user and the Agent.
   In our example, we enabled this option to converse with the Agent when reviewing specific points.
5. Knowledge Sources (KSs): KSs provide more specialized and personalized context. We added Knowledge Sources on accessibility best practices, WCAG rules, GAIA – Accessibility Guide for Autism Interfaces, and Horcel.

Testing Examples

The Agent is now ready! Using it is very simple. Test it directly in the StackSpot AI Portal by copying the text and pasting it into the Try area for review. Alternatively, access the IDE where your project is located and select the Agent. Check out examples of before-and-after AI in technical writing:

1. Link Accessibility
Issues:
The link text "Log in to the StackSpot EDP Portal" is somewhat descriptive but could be more specific about the purpose of the link.
Fixes:
Update the link text to clarify its purpose.

Before: **Step 1.** [**Log in to the StackSpot EDP Portal**](link);


After: **Step 1.** [Login to the StackSpot EDP Portal to access your account settings](link);

2. Image Alt Text Accessibility
Issues:
The alt text for the images is functional but could be improved by:
- Removing redundant phrases like "Screenshot of the StackSpot EDP Portal homepage."
- Adding more specific details about the actions being performed.
Fixes:
Rewrite the alt text to focus on the key elements and actions in the images.

Before:
![Screenshot of the StackSpot EDP Portal homepage upon login. The dropdown menu is open under the Avatar's name, with a red square highlighting the "My Profile" section.](image)


After:
![The dropdown menu under the avatar's name is on the StackSpot EDP Portal homepage. A red outline highlights the "My Profile" option in the menu.](image)

Before: 
![Screenshot of the StackSpot EDP Portal homepage in the Member's section. There is a red square highlighting the Edit button](image)


After:
![The Member's section of the StackSpot EDP Portal. A red outline highlights the 'Edit' button next to the 'Member Information' title.](image)


Before:
![Screenshot of the StackSpot EDP Portal homepage in the Member's section. There is a red square highlighting Password and Password confirmation fields](image)


After:
![The Member's section of the StackSpot EDP Portal. A red outline highlights the 'Password' and 'Password Confirmation' fields where users can enter and confirm their new password.](image)

Before:

Follow the steps below to edit your Account password:

**Step 1.** [**Log in to the StackSpot EDP Portal**](link;

**Step 2** Click on your avatar's name in the top menu next to the **'Create'** button;

**Step 3** On the Member's page, click **'Edit'** next to the title **'Member information** as shown in the image below:

**Step 4** Enter your new password in the **'Password field'**, confirm it in the **'Password confirmation'** field and click **'Save'**.

Done!

After:

# How to Edit Your Account Password

Follow the steps below to edit your account password:

## Step 1: Log in to the Portal
[Login to the StackSpot EDP Portal to access your account settings](link).

## Step 2: Open the Profile Menu
Click on your avatar's name in the top menu next to the **Create'** button.

![The dropdown menu under the avatar's name is on the StackSpot EDP Portal homepage. A red outline highlights the "My Profile" option in the menu.](/img/edit-password-1.png)

## Step 3: Edit Member Information
On the Member's page, click the **'Edit'** button next to the title **'Member Information'**.

## Step 4: Update Your Password
Enter your new password in the **'Password'** field, confirm it in the **'Password Confirmation'** field, and click **'Save'**.

## Confirmation
Your password has been successfully updated! If you encounter any issues, please contact our support team for assistance.

Your password has been successfully updated! If you encounter any issues, please contact our support team for assistance.

We also developed an Agent to help us correct errors and introduce improvements,  refining our work by eliminating common typos and grammar mistakes. Agents significantly reduce the time required for tasks that are usually time-consuming.

Conclusion

StackSpot AI is an innovative tool tailored for technical writing professionals. It offers features that streamline the translation process and ensure your content is accessible to everyone. 

Moreover, StackSpot’s use of AI in technical writing provides a range of functionalities that allow you to customize your workflow to your specific needs. The best part is that StackSpot AI is constantly evolving, with new features added regularly to enhance your experience. Stay tuned for updates!

For more information on how to get started with StackSpot AI, visit the StackSpot AI documentation.