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:
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
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.
What makes great documentation?
- 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.
- 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
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.
Based on research and competitive analysis, there were clear features that I wanted emphasize in the design.
Establishing a global framework
Building content blocks
Transparency and feedback
- 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?)
- 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?”
- 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.
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
Below is a selection of key screens from the docs project:
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.