ibm doc images should belong to the same 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?


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. Work progressed throughout Q2 2020 with an acute focus on video guidance.


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.


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. 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.

  • Offering Manager + Architect + Content Strategist: Jenifer Schlotfeldt
  • Designer: me
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
  • 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 conventions
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.

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...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.

No corresponding legend key 🗺

please add a legend expanding the acronyms used in these diagrams...what the heck is "MSR' ??

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?
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. As a result, the objectives evolved to:


2017 total images


content pages


2019 total images


total images
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.

  • 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

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.

  • Censorship of personal data
  • Guidance on leveraging SnagIt as the preferred tool
  • Annotative points
  • Emphasize accessibility requirements including alt-text

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.

  • 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
View more case studies:
RapidDeployIBM Cloud Docs SearchIBM Cloud Support Center RedesignIBM Cloud Docs TutorialsIBM Cloud Docs Imagery Guidance