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:
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 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.
- 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...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:
- 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
5000
content pages
2650
2019 total images
+383.6%
total images
