The UX of Docs

For the last few years, I have been working on the hardest/longest project of my career. – 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.

Identity and Words

A person just declared to the world that they identify with a certain group. Their DNA contradicts that assertion.  Who am I talking about?

Bruce/Caitlin Jenner
Rachel Dolezal

Bruce Jenner says, “I’m not a man. I am a woman.” The world says, “You go girl!” Rachel Dolezal says, “I am black” and the world responds, “No you aint!”

Why the double standard? What does it even mean to identify as black or female or any other label? Why do we feel the need as humans to classify things?

It turns out that classification is a critical part of human intelligence.  Our brains only have so much memory and CPU. We can’t unpack every single nuance about every single person. We need to group things together or we will lose our minds from the amount of data to be processed.

It’s impossible to treat all of humanity individually. We need to put labels on things so that we can make assumptions about them.  Assumptions that may be wrong some of the time.  Why do we make these assumptions? Simply to alleviate the mental workload of remembering all the details about each person. I can barely remember people’s names!

This line of thought led me to other labels.  Someone told me they are a “Designer”. I looked at their work and thought, “Not really.”  What does being a designer mean? If you WANT to be a designer, does it make you one?

What about being “Smart”? IQ clearly doesn’t measure things like empathy or awareness of others, which sometimes get thought of as “smart”.

Take an easy one. I’m “tall”. 6 foot 2 inches.  In the NBA I would be considered short, but compared to the average population I am tall. If I lossed my legs in a freak tractor accident, would I still be tall? Could I identify myself with tall people?

If I scan my consciousness into a nanobot swarm would I still be human?  What if I just has everything except my brain replaced with cyborgish material?  Is there a line?

Words are our most powerful tool to understand the world around us. Yet, they fall apart in almost every single instance of scrutiny.  Words are like humans.  They last a long time, but one good hit to the head and they die.

We either need better words or better brains.



In any disruption there are winners and losers. The internet has been the enabler to disrupt many businesses in the last 20 years. Some examples:

Music. Downloadable compressed audio enables ripping/pirating. Losers have been the record labels. Winners have been iTunes and small artists who want to get their name out there especially using YouTube and other sites.

Books. It’s nice to be in a bookstore, but it’s nicer to see reviews, recommendations all while in your pajamas. Winners have been Amazon and the small artists who want to self-publish. Losers have been book stores like Barnes & Noble and Borders.

Taxis. It’s been regulated for decades and become stable. However, location based phone apps have disrupted the entire sector. Winners like Uber and Lyft are displacing regular taxis.

Hotels. Winners like AirBnB come directly at the expense of hotels. Similar to taxis, the regulators are caught on their heels and don’t know what to do.

Travel. This got disrupted a long time ago, but the modern travel agent is an anachronism. This is still being disrupted as airlines and destination sites are all trying to become the hub for travel arrangements.

It’s happening all over the place. Job Seeking/Recruiting, Graphic Design, Engineering, Financial Advice and more. Disruption is a part of our lives now.

The question is: Will you be a loser or a winner when your sector is disrupted?

Google Drive vs. Microsoft OneDrive

I have been using OneDrive for a while now as our cloud service. However, complaints have forced me to reconsider. Here is a quick summary of my thoughts on the subject.

OneDrive pricing.

15 GB Free
100 GB $1.99/month
200 GB $3.99/month
1 TB $6.99/month (includes Office 365)

Google Drive Pricing.

15 GB Free
100 GB $1.99/month
1 TB $9.99/month (includes Google Apps)

They both offer office apps, but the full Microsoft Office suite is much more powerful and has both online and offline versions. With that said, Google is still 50% more expensive at the 1TB level.

Price Winner: Microsoft

Displaying Pictures/Videos
I have alot of photos online. I used to use Picassa, but it just didn’t the one feature I needed – folders! I organize my photos by year and then by month. Tags aren’t always good enough. I loved the Picasa photo editor, especially the red-eye removal, but without folders it just wasn’t going to work for me. Recently, Picasa has been merging into Google+. Actually, it’s pretty confusing what is happening there. I don’t use Google+, so I just don’t know what to think about their solution. With Picasa, YouTube, Google+ and Drive it is hard to understand what Google is doing. It feels like a lack of leadership/coordination to me.

On the other side, Microsoft does a great job of creating a nice interface for pictures. It has lightboxes and plenty of options. No red-eye removal, but the experience for viewers has been pretty good. My only complaint for Microsoft has been the lack of proper codecs to display DivX videos. It can display simpler formats, but I usually compress my videos using the DivX converter so they take up less space.

Display Winner: Microsoft

Sync Stability
If Microsoft had this part of the system under control, I would just give them the crown. It’s a better UI at a better price. However, the sync stability has been a nightmare. They are trying to embed this into the operating system, but honestly, they just fucked it up royally. Constant sync errors and confusing UI makes me worried about losing files constantly. The error icon is constant and the solution (re-open the file) is sketchy at best. Microsoft Office asks me the question, “Do you want to keep the server version or yours?”. This would be fine if they gave me a way to DIFF the two versions. How the hell should I know which is the right version?! They were supposed to be sync’d. No one else is editing!

You can see how Sync problems are by far the most infuriating issue. The importance of a stable sync can not be exaggerated.  Google’s sync, seems to be much more elegant. The progress of the sync is much clearer. It also asks you if you mean to delete on both the server and local. (Microsoft is unclear when this happens). The speed seems ok so far.  I have to test it more, but right now…

Winner: Google

Sharing and Identity Management
They basically have the same sharing model. However, Microsoft wants you to use their Microsoft account and Google wants you to use their Google account. (Duh!) So it comes down to which one of those accounts is more prevalent in people’s lives, especially me and my family.  The answer is: We all use GMail. None of us use Microsoft. My phone is Google, my watch is Google.

Microsoft has tried numerous times to improve their email client, but ultimately, I keep having spam problems. Using GMail (and most recently Inbox) eliminates spam from my life. I’m not switching. Also, the Microsoft Phone is still DOA, so I am not buying that either.

Winner: Google

Summary – Split Decision!
So for now, I switched all of my normal files to Google Drive but left all of the photos and video at OneDrive. There are fewer sync problems with photos because I am not actively editing them.  I will experiment with the photos at Google, but the extra storage expense is making me wary.

I hope this comparison helped you in some way. I’m just trying to educate, engage and entertain.  Not always in that order.

Buffer Overflow

In computer security and programming, a buffer overflow, or buffer overrun, is an anomaly where a program, while writing data to a buffer, overruns the buffer’s boundary and overwrites adjacent memory locations. This is a special case of the violation of memory safety.

I use it for human thinking as well. I say it when I have too much going on in my head and details start leaking. I start forgetting things. Additionally, when this happens, I start acting less likeable. Some might even say that I am intolerable in these circumstances. I tend to agree. It’s pretty bad being in my head when this happens.  Buffer Overflow is my kryptonite.

The only solution to buffer overflow is to let go of some of the things on your mind. It’s like having a house with too much stuff, you need to throw some of it away. Let it go, let it go…you know, from Frozen.


Ahh, I just can’t help myself.

As soon as you do, as soon as you clear your memory cache. The other things you are focused on start working properly. Good ideas start flowing. Creativity works. You can not be at the top of your mental game if your buffer is overflowing.

I tell my kids all the time, “Cool heads make good decisions.”

My brain is pretty big, but right now, I have a buffer overflow problem. It is literally stopping me from functioning properly. Computers and humans, we have so much in common. Don’t you think?

The UX of the Asus Zenwatch

I love my Asus Zenwatch and use it all the time.

The best use case: My phone (Nexus 6) rings in my pocket. It buzzes my wrist and I look at the watch.  I see a picture of the caller and their name.  I can swipe left (answer) or right (voicemail).

This simple interaction is so much more pleasant than taking out my phone to do the same thing. It doesn’t save THAT much time, but it is much more usable and elegant.

Second, it is stylish. I like the way it looks. It’s got swag. It’s not thick like the moto 360 and not smallish like the iWatch.


The operating system works well and shows me relevant information.

The watch face (after messing with a dozen different ones) I settled on is called Street Art. It looks great and has different art every 30 minutes or so.

I strongly recommend it if you use a Android phone.


Don’t Link the Word “Here”

I see it constantly. It’s a bad practice and I wish people would stop. Stahp!

Bad: See our great content about marketing here.
Better: See our great content about marketing.


  1. Google uses the link text as a hint to good keywords someone would use to find it. The word “here” isn’t something people search for.
  2. The link is small and hidden when it’s on the word here. 4 letters, versus 26 in the longer version.
  3. The underline is actually a great affordance for clicking. Make the affordance on the actual word they are interested in.

It’s not hard to do. Just put the link on the description of the content. Don’t be lazy! I know what you are thinking.


Ugh. I weep for the future.