Example of a revised architectural diagram with applied Carbon Design System V9 styling
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.
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 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
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
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.
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."
"Use better colors, mention other IBM Cloud services instead of Watson services, maybe update the logos"
'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"
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.
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.
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.
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
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
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