Design and doc-to-UI content reuse

IBM Cloud Pak for Data as a Service What's New experience

1 April 2022


  • Design collaboration
  • JavaScript
  • CSS


To sync the What’s New entries listed in the documentation with those displayed in the product UI home page, I created and added a utility to the documentation microservice, which gathered relevant data from the What’s New topic DOM and presented it as an endpoint for the product UI. Product development took it from there to display the first three and featured entries in the product UI.

The IBM Cloud Pak for Data as a Service product team had regular design meetings where they included product management, design, development, and content. At one meeting they discussed the What’s New experience and how the product What’s New information was out of sync with the documentation What’s New topic, published weekly. The content strategist felt that that the content team was in the best position to provide the single source of truth and had an idea.

Inspired, she returned from the meeting and asked me, “We can author the content in one place and reuse it for both the doc and UI, right, Gary?” She knew me well and how much I love content reuse. After a few seconds thinking it through, “Sure,” I said, “I’ll have to verify a couple of things, but let’s make it happen!” So we did. After a few design sessions to decide upon some fields and markdown tagging to add to the documentation source, I wrote the utility.

Because the entries in the UI each linked to the What’s New topic in the documentation, product design wanted the H3 entry titles in the documentation to be more prominent. We worked together on that and other page designs, and I wrote the CSS to make it happen.