commadot.com

The UX of Docs

For the last few years, I have been working on the hardest/longest project of my career.

http://docs.marketo.com – The Marketo User Manual

A few years back, I did a series of interviews of our customers. Specifically, I spoke to customers who thought the product was “too hard”. Turns out that part of the problem was the the documentation was suffering from the worst UX sins possible. These included:

  1. Factually incorrect/outdated content
  2. Poor tone (boring, cold, unfriendly)
  3. Verbose (like 10X longer than it needed to be)
  4. Complicated vocabulary
  5. Confusing, conflating multiple ideas
  6. Outdated and confusing pictures
  7. Poor organization

As a result of those interviews and our findings, the UX team (led by me) took ownership of the documentation process. It has been several years, but it finally is launched in public form. I tried to fix all of the sins mentioned and am quite proud of the results.

One thing I believe is that the UX team is actually a great group to give ownership of documentation. There are two primary reasons:

  1. No one knows the details as well as the designer of the feature
  2. Designers will make it fun and easy to read

However, there is a problem.  Designers are mostly (not all) prima donnas who think that writing docs is beneath them. I had a terrible time getting designers to pitch in.  Additionally, their skills at summarizing a design into a teachable article was shockingly poor. A great designer should be able to teach people how to use the product they design, wouldn’t you think?

Alas, it was not to be.  I found a couple of people who were willing to do the real work with me. (Shout out to Reza Farpour and Anna Zeman! – both were instrumental in getting this thing done.) They did a tremendous job, although after a while, it did wear even on them.

I consider the docs work to be true User Experience Design. When a customer is confused and doesn’t know how to achieve a goal, they either go to the community forums or look up the documentation. That is the moment you can come to the rescue with a simple walk-through and make them happy.

Good documentation contributes to good UX. It’s a chance to have personality and create an emotional connection. It usually hits people when they are at their most vulnerable. A great UX at that moment will create a super fan.

Technical detail: We used the Atlassian Confluence wiki as the CMS. It has this wonderful feature where you can paste (from the clipboard) any image. It automatically uploads it to the server. Not even my beloved WordPress can do that. This brilliant feature alone more than quadrupled our productivity.

I have recently handed the reigns of the site to another person. We think he will be a good custodian of the awesome nature of the site. I hope he will take good care of my baby. It has been the longest and most rewarding effort of my career.

When you get a chance, click HELP inside any application. Think about the UX.

Comments

3 responses to “The UX of Docs”

  1. Maria Pergolino Avatar
    Maria Pergolino

    Glen, I love the effort Marketo (including your team) put in here, and the experience has definitely improved and evolved greatly over the years. From a UX experience though, I’m curious why articles don’t start or end with examples of the outcome. I constantly struggle because I don’t know what the final output should be/look like.

    For example, if we look at an article about publishing a poll, we see great instructions, but there is no sample of a poll in the post, so I’m not even sure if what I’m trying to do is create a poll (maybe I am really trying to create a sweepstakes but don’t know the lingo), and maybe I am not actually looking for the directions, but just a sample. https://docs.marketo.com/display/public/DOCS/Publish+a+Poll Almost every time I search for something in community (or docs) that I have this problem.

    Do you see this as the next part of the evolution, or am I potentially alone in this request?

    Reply
    1. Glen Lipka Avatar
      Glen Lipka

      Ive officially handed ownership to someone else in the organization, so I am not sure of the next phase. With that said, I tried to have the outcome where possible. Sometimes it was more difficult than others. The one you pointed out should probably be improved. See the button on the bottom of it that says, “How can this article be improved?” click it and tell them. 🙂

      Reply
  2. Dan Lipka Avatar
    Dan Lipka

    Somewhat recently, I upgraded my website and whenever I approached the design company with “How do I do something”, they always responded with a video explaining the answer (video of them doing whatever I was asking for with commentary about it). I’ve found these videos to be super helpful and I remember them remarkable well. I went to the docs site and randomly got this page, https://docs.marketo.com/display/public/DOCS/Get+Set+Up+and+Add+a+Lead, and it made me think of the video. Having a person (a voice) guide you through something like this would be pretty cool. On a similar note, I recently installed a garbage disposal and the written directions were almost useless. The youtube video that some random plumber had was infinitely more useful.

    Reply

Whatya think?