AI-Powered Techniques for Technical Writers

Share this event

Cheryl Solis, a renowned figure in Silicon Valley's technical writing community, shares her own tips and techniques on using AI to improve her technical writing processes. This session is a must-watch for anyone looking to understand the foundations of technical writing and the practical applications of AI tools like Storytell SmartChat™.

Understand Your Audience with Personas

Knowing your audience allows you to create documentation that is appropriate and relevant to their needs. For example, Cheryl mentions that she writes for developers in the GraphQL space, which is a specific domain in programming. Understanding the different types of developers (e.g., front-end, back-end, full-stack) helps in tailoring the content to their specific tools and skills.

Here’s how she’s doing it with Storytell SmartChat™:

1. Cheryl starts by developing basic personas based on her familiarity and interactions with developers.

2. Recognizing the need for a more comprehensive and global perspective, she uploads content containing the information she gathered about the developers into Storytell. (Learn how to upload content on SmartChat™ here)

3. Cheryl creates Tags within Storytell to organize and refine those content. For example, she creates a tag called “Wider audience appeal" to ensure that the personas reflect a diverse and global audience. (Learn how to create tags on SmartChat™ here)

4. Under this Tag, Cheryl uses this prompt: “I want to appeal to a wider audience from different cultures. Generate GraphQL personas that represent different, more global audiences and their skill sets.”

This will yield this result:

You can also chat with more than 1 tags for complex outputs like how Cheryl does when she needs to define custom scope. She chooses both the “Wider audience appeal" and another Tag “scopes,” which contains content detailing the desired parameters for her audience.

The result:

Create and apply tags to generate DITA topics

Cheryl uses Storytell to create Tags to generate DITA (Darwin Information Typing Architecture) topics. The structured approach of DITA helps in ensuring that the documentation is clear and complete. Each type of content (concept, task, reference) has its own set of guidelines and structure, which helps in covering all necessary aspects comprehensively. DITA's modular nature makes it easier to manage large volumes of documentation. Each module can be developed, reviewed, and updated independently, which is particularly useful in fast-paced environments like Cheryl's small startup.

Here’s a detailed breakdown of her process:

1. Cheryl uploads various types of content to Storytell, including blogs, videos, and other documentation she needs to create DITA topics for. For example, she uploaded a blog about rate limiting and a video demo related to her company's applications.

2. Once the content is uploaded, create Tags to organize the content. For instance, she might apply the "DITA Concept" tag to a blog post and the "DITA Task" tag to a video demo.

3. Using the chat functionality within Storytell, Cheryl generates DITA topics based on just the content within the selected Tag/s. For example, she might use the prompt: “Apply the DITA Task tag to this content and generate a task topic in markdown format."

4. Cheryl reviews the AI-generated content to ensure accuracy, completeness, and clarity. She acts as the gatekeeper, making necessary edits and enhancements to the content.

In using AI, it's great to leverage it. But I am the gatekeeper. I am still responsible for ensuring that every single word in the content is accurate, complete and has clarity. I can never turn off being a gatekeeper, but I can allow AI to assist me doing tasks that would be extremely difficult for me to do at speed. -Cheryl Solis Technical Writer, Stellate

Applying Style Guides and Doc Linting

Style guides ensure that all documentation follows a uniform structure and style, which is essential for readability and professionalism. This consistency helps users navigate and understand the documentation more easily. Doc linting involves applying rules to content to ensure it adheres to the style guide. This process can identify and correct issues such as inconsistent heading formats or incorrect font usage for commands and API callouts. Cheryl mentions using Storytell AI to apply these rules, which not only identifies issues but can also fix them, ensuring the documentation meets the required standards.

Cheryl mentions that for a rookie technical writer at a small company who needs a style guide, Storytell can act as a scaffolding, helping writers overcome the blank page fear and provides a structured starting point. She emphasizes that while Storytell can help create the initial structure, the writer still needs to refine and complete the style guide to make it fully functional.

If you're a new writer and the only writer at a small company and you need a style guide, you can leverage Storytell to create the scaffolding, so you can get started because otherwise it might seem like an overwhelming task. -Cheryl Solis Technical Writer, Stellate

Here's a detailed breakdown of her approach:

1. Cheryl creates specific content rules, such as formatting all head level titles in initial caps and ensuring in-text commands, APIs, and code are in a consistent monospace font. These rules are then uploaded into Storytell as tags.

2. Upload the documentation content that needs editing into Storytell and applies the pre-defined Tags that contain her content rules. For example, she demonstrates how headings that were initially inconsistent in capitalization are corrected to follow the initial caps rule. Similarly, in-text commands and API callouts are formatted in a monospace font as per the rules defined in the tags.

Edited documentation result on SmartChat™

The types of files Cheryl is uploading to Storytell include:

1. Blogs

2. Text documents

3. Videos

4. PDFs

5. PowerPoint presentations

6. XML files

7. Markdown files

Going Beyond SmartChat™ - Explore Our New Beta

Cheryl showcased how she utilizes SmartChat™ to understand her personas, employing prompts each time she undertakes this task. These repetitive tasks are precisely what our new Beta aims to streamline.

How does it work? We've developed use-case specific pages where users simply upload their relevant files, and our product takes care of the rest. For instance, consider the persona task: by using the dedicated use-case page on our new Beta, you can effortlessly manage this process. Explore it here: Generate GraphQL personas

1. Upload your relevant files to do the task