Reuse across doc and UI

A What’s New experience

01 Apr 2022

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

Sequence diagram capturing the API message flow UI to Doc frontend to IBM Docs and back through to UI.
HTML code indicating the classes that the author attributes to What's New entries for the API to find in the DOM.

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.

The rendered What's New HTML page with the custom styles.