With the push for open source gaining traction at Adobe, the need for a more cohesive developer experience grew. The focal point of this effort was the fragmented documentation ecosystem—the perfect test case for our newly mintedModular Content System concept.
There was a lot of low-hanging fruit for this project: poor UI and UX, no search functionality, etc. But I still wanted to understand at a higher level what our third-party developers needed to have the best docs experience possible.
To gauge general sentiment about our developer docs, I reached out to product teams and various third-party developer volunteers to fill out a survey asking about their experience with our documentation and any areas of improvement. The results identified several areas of improvement:
64%
80%
48%
It was obvious from the survey we needed to improve not only documentation design, but the quality of our docs in order to reestablish Adobe as a leader in the developer community.
How might we design developer docs to help developers do their job and reestablish trust in Adobe as a community leader?
Research + Validation
I kicked off the project by holding a workshop with various Adobe product teams, where we chatted with third-party developers and reflected on their feedback, as well as map the user journey of someone implementing an API or service using our docs.
By the end of the day, we discovered several areas of improvement:
- Our users struggled to figure out where to start If they navigated to Adobe.io, documentation for their API or service was buried under several layers of marketing pages.
- Our docs were ugly and difficult to use Plain and simple. They lacked finesse and had poor UX.
- Our users were confused because Adobe's docs were spread around multiple different websites Because of the difficulty publishing on adobe.io, many teams were rolling their own documentation using Swagger or Gitbooks. Most of the time, links to these sites weren't present on adobe.io, so searching for the correct documentation could be difficult.
- Lack of community and support One user we talked to said they spent 2 hours one day trying to figure out how to report a bug he found in a product's API. They finally had to reach out to someone on Twitter to resolve the issue. Easy access to support was an essential piece missing in our docs.
During the workshop we also created some third-party developer personas:
We then mapped out a customer journey, highlighting key touch points to better empathize with our users.
I was able to establish a goal framework and a set of questions that would lead my design and ideation phase.
What makes great documentation?
The concept of "good vs. great" documentation kept coming up in conversation, and I wanted to dig deeper into what that meant. I did a comprehensive competitive analysis and talked to as many developers as I could about what they considered to be "great" documentation.
I asked developers to give me examples of amazing docs experiences. The top websites were Stripe, Square, and Atlassian. I focused my competitive analysis on them:
From there, I was able to establish my goals for this project:
Constraints
- Strong opinions about solving documentation pitfalls This project came with many stakeholders, all of whom had attempted to solve Adobe's documentation issues in the past. Making sure everyone felt heard and valued was imperative to the project's success
- Lack of alignment Since there were so many opinions, there were many different solutions. Rallying all of our product teams towards one unified direction was going to be a challenge, so full transparency was needed.
- Timeline Because of COVID, our timeline was tricky. We lost engineering resources early on, so we had to scrap one of our most requested features, Search.
MEASURING SUCCESS
- Are our docs able to be used by all developer teams at Adobe? Similar our MCS success measurement, our goal was to onboard as many teams as possible to the new documentation. It was imperative our docs were flexible and modular, but also followed best practices for quality documentation.
- How engaged is Adobe's developer community? One key piece of our documentation redesign was adding in features such as contributing on Github, joining discussions on forums, giving feedback on documentation pages, etc. To drive the community aspect, we wanted the level of involvement to be as high as possible.
Flexible, but with clear boundaries
Most pieces of the Modular Content System were designed to be fairly flexible. Page design, information architecture— as long as they loosely followed a template, teams were encouraged to be creative. As I started the docs project, I quickly realized we had to have firmer boundaries around what we defined as "best practices". Adobe's current documentation varied wildly from product to product. Differing Information architecture and page structure was inconsistent and felt confusing for users
Information architecture
Adobe's docs needed a unified information architecture. I started this process with a card sort exercise, involving members from the previous workshop I did along with various stakeholders. We came up with common questions from our customer journey and began categorizing them. In the end we came up with 4 different pages:
Docs Templates
As covered in the Modular Content System, defining templates for our content authors was an important step for publishing. I uncovered during our information architecture deep dive and subsequent interviews with stakeholders and users, that the docs templates needed to be specific but flexible.
Global features
Based on research and competitive analysis, there were clear features that I wanted emphasize in the design.
Clear navigation from adobe.io to desired docs
Search within the docs website
Clean and consistent UX and UI between all docs
Wayfinding and next steps clearly defined on a global level
Feedback and engagement highlighted throughout documentation
Establishing a global framework
To establish best practices, we needed to have a global framework that each template could be built off of. I iterated different layouts and page structures, until I came up with one that I felt would test the best with users.
The final framework design was influenced heavily by well-established docs design, a global top navigation, side navigation, search bar, and a table of contents.
Building content blocks
There were many content blocks that went into our documentation design. I want to highlight my design process for one of the more in depth features: our "Was this page helpful?" content block.
Transparency and feedback
Transparency and feedback was at the top of our list of features. I knew right away I wanted to have a question at the bottom of each page that asked users whether or not they felt the page or code they were viewing was helpful. There were versions of this on different product documentation throughout Adobe, but I felt most implementations were vague, and some product teams admitted they barely used the dated they received since it wasn't incredibly helpful.
- Data received was vague (only a "yes" or "no")
- No follow-up questions on what was working or not working
- Lack of social proof (how many people agreed or disagreed with you?)
Using the data I had collected from chats with third-party devs, I began a list of assumptions to start designing with:
- Most of the time, people wont' leave feedback unless the page or code block is entirely unhelpful or has a mistake
- Social proof is important for deciding if something is worth reading
- Our users are motivated to give detailed feedback if they feel it will be listened to
From there, I ideated designs, emphasizing simple language, social proof, and ample room for comments.
Due to ongoing COVID-19 restrictions, I conducted my usability testing remotely over Zoom, with Adobe Creative Cloud developers. I asked participants to share their screens and think aloud while being recorded going through the prototype. I asked users to place themselves in the following scenario:
“I want you to imagine that you are brand new to Adobe CC APIs, and need to build an integration for Adobe Photoshop. You land on the adobe.io website and navigate to the Photoshop docs. How do you start this project?”
After conducting my usability tests, I created an affinity map with key insights, behaviors, and findings during the tests. Participants commented on the approachability of the docs, as well as excitement over easy wayfinding and navigation. The key insights:
- Many users commented on the placement of the version number. It didn't match up with where they expected it to be
- Users spent the most time on the overview page, getting acquainted with the docs.
- Almost all of the users immediately used the search feature to get started
- Users were confused with where "on this page" was placed. The placement was at the very top of the page, and as they scrolled it would move to the right of the content. If the page was very long, the ToC would take up a lot of room, and users would have to scroll a while to get to the content.
View interactive prototype of usability test
Based on observing users interacting with the prototype, I prioritized a couple of changes:
- Move the version number to a spot that corresponded with the product docs
- Keep "on this page" to the right of the content at all times
- Emphasize writing quality overview pages to content authors
RESULTS
Below is a selection of key screens from the docs project:
I really enjoyed working on this project, and it was incredibly satisfying seeing it come to life and the response from the developer community inside and outside off Adobe. Some quick stats from a couple months after our launch:
43
5%
3
helping teams onboard
- Enthusiastic users make for the best products This project initially intimidated me because it felt like so many people were invested in its success. As the sole designer, that was a lot a pressure (and stress). I was constantly checking in with teams, third-party devs, designers, and stakeholders to gut check decisions. More often than not, a solution I would have never thought of would materialize, which in the end made for a much better product and user experience.