Missy Yarbrough
Product Designer

Documentation images should clearly feel like they belong to the same IBM family.

Inconsistent styling and outdated files impede user trust of digesting information.

Initial Opportunity
How might we improve consistency across visual styling, ease the creation process, and elevate user trust of documentation information?

Outcome Thus Far

The official release of the first iteration of the IBM Cloud Docs Imagery Guidance was issued in Q1 in 2020 with primary focus on static imagery types. Ongoing work has progressed throughout Q2 2020 with an acute focus on video guidance.

Overview

I accidentally stumbled into the world of IBM Cloud Docs by way of curious desire to uncover existing illustrations within our product. To preface, the Bluemix platform (now currently the IBM Cloud platform) mostly focused on UI elements with odd moments of pop-up robots in our 404 pages. Even though I had initially intended to dive deeply into the illustrative side of the product, I uncovered an opportunity to investigate and address the difficulty of creating more consistent imagery at large scale.

Background

Once upon a 10% "fun design" time, I challenged myself with the initial intent to incorporate illustrations into our current platform experience in a relevant and meaningful manner that reinforced the branding experience.

To start understanding, I decided to find current examples within the Bluemix platform (now currently IBM Cloud), discovering that most imagery usage focused on UI elements with odd moments of pop-up robots in our 404 pages. Even though I had initially intended to dive deeply into the illustrative side of the product, I uncovered an opportunity to investigate and address the difficulty of creating more consistent imagery at large scale.

Primary Skills Utilized

  • competitive research

  • audit

  • content design

  • synthesis

The First Audit

Over the course of May 2017, I dedicated time to evaluate the entirety of IBM Cloud Docs for its imagery, noting each item's source link, image type, and image source. While I ultimately accounted for ~550 items over 300+ documentation pages, I was able to identify emerging patterns including:

Types of imagery

  • Diagrams

  • Screenshots

  • Icons

Inconsistencies

  • Format

    • Most images were JPG or PNG format.

    • Some are non-animated GIFs.

    • SVG format is preferred for scalability but knowledge of output practices is not consistent across teams and individuals.

  • Styling Examples

    • 1

    • 2

    • 3

    • icnhostnormalwhtbckgrnd30x38

    • calloutlabel5

    • disable

  • Naming convention

Stakeholder Painpoints

While the 2017 audit proved insightful and helpful for a baseline understanding of our assets, I also inquired about the technical complications from our internal end.

  • Not every service has a dedicated writer.

  • Writers are sometimes developers, offering managers, and technical writers.

  • Writers lacked time, budget for image tooling, and visual references and knowledge of imagery creation.

User Pain Points

Due to other assigned work priorities over the years, I was not able to revisit for some time. Upon reflection of 2017's audit, I realized that I had a gap in knowledge in understanding our user's perspective. Therefore, I decided to take a look into our Usabilla feedback to understand how our users feel about the existing imagery assets.

  • Lack of visual aid in documentation
    "In my opinion, documentation with visual diagram in it is key to understand new concept. To be honest, IBM documents lack this. Would appreciate IBM consider and include diagram where applicable to understand the concept."

  • Visual datedness
    "Use better colors, mention other IBM Cloud services instead of Watson services, maybe update the logos"

  • Mislabeled images
    'The diagram uses the label the "Customer Colocation" but further down the words state "Colocation Services: None". This appears contradictory to me but may be valid perhaps further explanation is required here or the label needs to be updated.'

  • Overcomplicating instead of simplifying
    "There is no visual example for this and no easy way to figure out what this paragraph means for someone uninitiated to cloud functions or whisk or actions or openwhisk or I don't even know what to call what. Why does the dashboard not give the fully qualified name for the function in the first place? Why does the user have to do brain surgery when IBM could do a simple string concatenation?"

  • No corresponding legend key
    "please add a legend expanding the acronyms used in these diagrams...what the heck is "MSR' ?? thanks"

The Revisit

Although I accidentally stumbled on an area of need, I discovered that people are struggling on both ends of the experience. If design can alleviate this struggle, then people can work better doing what they originally intended.

Writers, contributors and users can get to what they do best—creating meaningful content and building solutions.

Evolved Opportunity
Compare the relationship between outputs to the 2017 data. By comparing the data, determine which areas to prioritize improvements for promoting consistency of IBM Cloud imagery assets.

The Second Audit

In Q2 2019, I completed a second audit of the public IBM Cloud documentation's imagery which resulted in over 2600+ items which highlighted significant increases in the use of screenshots and diagrams compared to the 2017's initial audit. 

Evolved Objectives

  • Apply design thinking to producing a standardized imagery solution, and scale it for use to distribute to team.

  • Define and share the internal documentation practices on imagery while adhering to current styling consistencies defined by IBM's Carbon Design System V10 and the IBM Design Language.

  • Enable end users to better understand and trust visual assets (including but not limited to screenshots and diagrams) so that they can get to productive use more quickly and easily.

~548
2017 total images
~2650
2019 total images
+383.58%
increase of total images
~5000
content pages
Example of a revised architectural diagram with applied Carbon Design System V9 styling

Example of a revised architectural diagram with applied Carbon Design System V9 styling

Architectural Diagrams

Akin to a Lego set amassing to an entire building or ship, IBM Cloud users need to be able to understand how our offerings work together. Architectural diagram assets are freely offered at AWS, Azure, and Google, but that is not currently offered at IBM as of mid-2019.

Opportunities

  • Shared asset libraries across numerous tools (Powerpoint, Keynote, Sketch, Illustrator)

  • Guidance on labeling and element placement

  • Clear definition on how to export to SVG

  • Translation simplification

Example of an updated screenshot reference with annotation points

Example of an updated screenshot reference with annotation points

Screenshots

Helpful tutorials generally include screenshots for a user's reference as they proceed through the step-by-step process. Screenshots in the IBM Cloud Docs ecosystem are inconsistent in quality and are often confusing due to few defining labels.

Opportunities

  • Censorship of personal data

  • Guidance on leveraging SnagIt as the preferred tool

  • Annotative points

  • Emphasize accessibility requirements including alt-text

Preview of a Live Video

Preview of a Live Video

Videos

With motion as a powerful medium to demonstrate process, there can be a myriad of different use case which results in variance in quality without any guidance/reference. Videos that are used for marketing/promotional purposes need to be distinguished from those that are utilized for documentation.

Opportunities
  • Reusable assets including IBM-approved opening/closing, transitions, and logos
  • Guidance on creating/capturing video and audio material
  • Promoting accessibility requirement including captions and translatable transcriptions