IDE code documentation plugin
Swimm aims to streamline knowledge sharing among dev teams by improving code documentation practice and workflow. To avoid context switch, we've shifted from a web application to an IDE extension, enabling developers to code and document seamlessly within their daily environment.
Role
Information Architecture
UX
Duration
Aug 2022 ~ Nov 2022
Visit live at
app.swimm.io
Problem
User's biggest expectation is to be able to use the core features — create, view, and maintain documents, without leaving their IDE. We are basically bringing our existing web features into a new environment. There are some basic research both design and technical side:
What is possible in the IDE extension?
Which part of the experience need to be altered to fit the IDE environment & dev workflow?
How do we implement the features so we can refrain from re-building existing component in the codebase, while making it scalable in other IDEs?
To summarize, we have a pretty defined problem statement:
How might we make Swimm docs creation, viewing, and maintaining intuitive for devs in the IDE while keeping the development cost-effective?
Research insights
We were able to narrow down pressing questions through researching extension guidelines, talking with devs and mapping our feature sets. Here are some key insights that is worth mentioning:
Dedicated a sidebar for scalability
Having a sidebar grants a centralize place for our app's feature and provides room to scale.
Adjacent editor & code view
For editing experience to be smooth, the editor and code should be equally accessible.
Code highlighting mechanism
Add code to doc experience need to be altered since code is the primary entity in IDE.
A discoverable referenced code
There is an opportunity to present a Swimm doc for a referenced code, which could be useful when coding.
Leave out the admin stuff
Actions like login and feature enablement aren't frequently use and can be redirected to web.
Initial Schema Proposed
Sidebar home - a dedicated panel that contains information like user, workspace, configuration info, document list & their statuses within the repository, creates doc entry point
Code files - a visual cue that allows user to discover the doc while they code
Editor panel - a panel the opens to the side of code file for core product offering like editing, viewing, maintaining individual doc
Doc list - a section within their explorer panel that present doc list with their statuses in relevant to the "code files" they open
Revised Schema - Editor
We got a major pushback from the developers when showing the initial architecture to them. To put their concern in a sentence — "Creating doc on a panel does not feel natural to devs at all." With this feedback, we brainstorm with the devs and come up with iteration direction
Create like normal code file, move away from panel representation
Remove all unnecessary help & resource
Render the editor from the webapp as is (tech implementation)
Now that we're aligned with the editor's infra and tech implementation, let's look into how we could bring in the core functionality — adding code snippets to our doc.
Add code to doc exploration
Two flows were proposed to achieve adding code snippets to our editor:
Here's an outline of the two flows.
The first option sound ideal, but we soon realized this is technically impossible. The universal copy paste command in the IDE can not register where code is being copied from without a special "listening" command, as a result it would only be copied as normal text string.
This lead us to go with the second option, present a popup that listens to the next code user highlights and render them visually. Editing each added snippet also use the same mechanism.
The home panel will takes care of user logged in information and repository configuration, this panel changes depending on the situation they're in. As we see, resources was also a big part of the experience regardless of whether or not they are logged in.
Outcome
28 companies moved to using IDE during the first month
+24.57% doc creation in IDE
25,000+ total plugin downloads in both VS Code & IntelliJ
