Helping users get better help

Daniel Fosco
5 min readJul 30, 2017

Hi! This case study is part of my product design portfolio. Feel free to look around at www.danielfos.co

VTEX Help is the documentation center for the VTEX platform, an application built with React on top of the Contentful CMS.

I was the lead designer for the project, taking over the product and going through a major refactor, rebuilding the product and assembling the team around it in the process.

I joined the Help Center project shortly after it was started, with a roadmap to deliver internationalized documentation to all of our customers and integrate the docs within the platform.

My initial role as lead designer for this project was to build on top of this roadmap and serve the documentation team with a product that would speed up their workflows, modeling the experience around the content to better serve our customers.

After a initial discovery phase and a few iterations, one thing became clear: the project was in a bad position. With no developers on the team, evolving the WordPress codebase with external contractors was becoming increasingly harder. To top it off, the support team (responsible for the docs) was also having a difficult time adjusting WP to their editorial needs.

There was no way out of this — in early 2017, we needed a full rewrite.

Old Help Center in WP

Making the case for a rewrite

To make this work, we used Contentful, a headless CMS (that delivers content only via API) that allows for flexible content formats and full support for internationalization.

With the CMS locked in, I borrowed the front-end developer Guilherme Resende from the InStore team to help me build a proof of concept for a React app connected to the Contentful API.

We had no idea it was going to work, but if we were going to change platforms, we needed to make sure the team understood the absolute necessity and value behind it.

That’s why we decided to keep everything of the visual design (it was supposed to be a refactor, not a redesign) and show a roadmap of features only the new platform would allow.

Me and Guigs presenting the proof of concept and migration plan

The proof of concept was a success. Not only was the app quick to build, but we made sure to show the team how exactly we wanted to expand the product with this new API-centric platform.

Concept for documentation integrated into the VTEX product

Rebuilding the product

From this point on, we knew what expected us. While Guigs wasn’t able to stay on the project after the green-light, Gabriel Koz joined as the dev lead, later followed by developer Vera Osokina and dev intern Alan Carpilovsky.

Together we moved on to create a React app with server-side rendering (so we wouldn’t lose any SEO) and full i18n support.

Meanwhile, I sat down with Breno Barreto, our documentation editor, to map all of our content formats and architect the new content model in a way that was flexible for future iterations, but at the same time provided for a sane migration (spoiler alert: migration was hell regardless).

When the content people are running the asylum

On the UI side, I was rebuilding the interface using tachyons, a functional CSS toolkit that reduced our stylesheet size in 77%. Overall, this new version loaded 78% faster than the old WP site and improved our speed index from 6121 to 1842.

More importantly, the project now had a solid codebase and was a first-class citizen in the company with a dedicated team, meaning it would keep evolving after the initial release.

Sweating the UI details

To make our relaunch even better, the new VTEX brand was unveiled right after us, so bringing that into the UI also improved the visual design all around ✨

Becoming a product team

After releasing with good reception in the company, we had a stable product and team— now with a design intern, Jenifer Emmanuel. But with a hefty backlog ahead of us post migration, we were starting to drift on which features were the most relevant to implement.

To help us guide the product, Fabio Martinelli joined the team as product lead, and organized a backlog that prioritized user satisfaction according to one key metric: support tickets closed with documentation.

This metric signified that users were opening support tickets for problems that were already documented… meaning, they were using our support agents as the Help search engine! That told us somewhere along the funnel, our product failed.

To tackle this metric, we reordered our backlog by value × effort and plotted the result on an action priority matrix. This allowed us to get the low-hanging fruit out of the way, while consistently moving towards improving our key metric.

This work is just beginning, but it has already made a huge difference on our rhythm. It's a first good step for organizing the team, and we’re excited to see what we’ll be able to achieve in the next few months!

Thanks for reading! Reach out or comment if you have any questions or feedback. ✌️

Bits and Pieces

Sketches and other highlights from the design process

Early survey to measure user satisfaction and get feedback
UI and sketches for the (discontinued) tracks feature
Discussing component architecture and i18n strategy with Koz
Concept and UI for the new Known Issues section
Internal interviews conducted by me and Jenifer with support agents to understand issues with the editorial workflow



Daniel Fosco

senior product designer • always learning • made in 🇧🇷