Last few weeks, we successfully launched the beta version of our AI features on our platform! We hope you had the chance to explore and play around with it. Today, we want to take you behind the scenes of one of those features: AI-generated content. We will highlight some of the challenges we encountered and the improvements we made along the way, giving you an insider’s perspective on the development journey.
What constraints are we working on?
First, we had to ensure that the feature is supported in both our web app and IDE plugins. Although the IDE plugin is a trimmed-down version of our web app, it was crucial to assist the clients that use it.
Next, we want our AI model to utilize our platform capabilities when generating content. One unique advantage of writing documentation within our app is that users have direct access to their codebase. This allows them to provide contextual code snippets or paths to generate better responses when needed. Lastly, we want to narrow down our use case, targeting users who already had a clear understanding of the topic they wish to document.
The version 0
Before we dove into designing, we revisited a previous feature called “Guided Creation” to gather valuable insights. We discovered some key takeaways from this version:
- Every other “Architectural” doc looks identical. Due to manually defined sections for each document type, the suggested content lacked variation, resulting in documents that looked strikingly similar.
- The feature is not meant to generate the whole doc for users. Many users abandoned the process halfway, preferring to continue writing on their own. The end goal of the feature isn’t to generate a perfectly fine document that they could just commit to but to provoke inspiration and guide users throughout the creation when they need it.
- Guidance for refinement is necessary. Having users manually provide specific details such as the document category, the file or component location, the function call’s starting point, etc is crucial for generating highly relevant content sections. We need to find the right balance to show the prompts without disrupting users’ workflow is a challenge.
Initial exploration
With the constraints and insights from the previous version in mind, we set out to create a smarter content suggestion mechanism and an improved user experience.
- ✅ AI experiments: We were determined to leverage our customized AI to analyze the document title and return the most suitable doc type along with their relevant topic suggestions. The results were remarkable. Not only did AI accurately identify the document type, the diverse suggestions hardly resembled one another. This also lessens the manual work required on our users.
- ✅ Creative prompt appearances: Optional follow-up prompts and placeholders were embedded throughout the AI-generated results. This gives users the freedom to either use the general topics or provide codebase details to refine the suggestions.
- ✅ Common entry point: The ideal location for this feature would be the main editor, ensuring accessibility in both our web and IDE environments.
So, here’s a snapshot of the envisioned flow: ****Users start by writing the title of their document. They are presented with an option to “Create with AI”. When triggered, we run the analysis with our AI model. Users can review the suggestions, fine-tune each section with additional info, and seamlessly incorporate the content into their document.
After putting it to user test, we found a general visibility issue. Many users failed to notice or utilize the AI button, challenging us to find a new entry point for this exciting feature.
Increase visibility with inline suggestions
In our next iteration, we made a significant change by removing the AI button and running the AI analysis immediately in the background after users write their document title. We relocated the entry point of the feature to the body of the document, where users actually write the content. Each empty text block in the body is now accompanied by an AI icon alongside existing quick actions and their placeholders, allowing users to access AI-powered suggestions as they start a new line.
Although the visibility of the feature significantly improved, user testing revealed additional usability challenges:
- Limited visibility of lower suggestions: Stacking suggestions one after another made it hard to see lower content blocks without scrolling.
- Expanding and collapsing behavior: Users found the hovering-triggered expanding and collapsing behavior disruptive.
- Information overload: Adding content blocks to the document resulted in a potentially overwhelming amount of text.
- Delayed refinement: Users primarily refined content suggestions after adding them to the document, rather than fine-tuning them beforehand.
Overcoming usability challenges
To enhance the overall user experience and address these usability issues, we made several adjustments:
- Clear sectioning & grouping: We encapsulated the user interface within a drawer. This allowed us to rearrange the layout and group all section titles together, ensuring that all available suggestions were visible without the need to scroll, even those at the bottom of the list.
- Re-defined component interaction: We replaced the hover-triggered expanding and collapsing behavior with a click-based interaction, providing a more pleasant and seamless experience. Details are now revealed in a dedicated container with a fixed height to prevent constant resizing.
- Micro-animation to the rescue: To tackle information overload, we introduced a streaming text effect and scrolling to view, gradually displaying suggested content into the document. This reduces the overwhelming feeling of excessive text.
- Support building document structure first: We remove the optional refinement area altogether, allowing users to focus on building a solid structure for their document with the general suggestion. They could always refine the content later with the placeholder we showed them.
We’re confident that these enhancements will elevate your experience with our AI-powered content suggestions. Stay tuned for more updates as we continue our efforts to make creating tech documentation effortless for you! In the meantime, if you haven’t checked out Swimm AI, take it for a test run.
