Roles

Software Developer, Technical Writer

Skills

Web design, CSS, IBM Globalization Pipeline, Travis, CI/CD, Hugo, Ruby, JavaScript, DITA, XSLT, Bootstrap, Git, Support, Training

Responding to a content strategy request, I applied IBM Carbon Design CSS to documentation landing pages, built them with Hugo, and translated them with the IBM Globalization Pipeline Ruby and JavaScript SDKs. A couple of releases later, I restructured the pages in DITA so that we could take advantage of the IBM Docs standard build process.

Customers chose Cloud Pak for Data services from a product catalog, which was nicely designed with the IBM Carbon Design System. Each service in the catalog linked to a landing page in the documentation, which provided more information about the service.

Content strategists worked with the design team and me to come up with a design layout for the landing pages that nicely transitions from the design experience of the catalog to that of the documentation system.

Although the IBM Docs platform contained the IBM Carbon Design libraries, the standard markdown and DITA builds didn’t make use of the style classes necessary for the landing pages. I therefore used Hugo as a framework to create the landing pages to easily make use of the extra Carbon styling. The main reason I turned to Hugo, however, was to make extensive use of templates so that writers could add data for each page easily in YAML files, without touching the common page HTML design layout. I even wrote a custom web form with ExpressJS, Bootstrap, and the GitHub API to make it even easier to provide data for each page. Also, because the build was outside of the standard build process, I created a custom translation workflow that made use of the IBM Globalization Pipeline CLI commands and JavaScript SDK.

Two years later, all content built through the standard build process for IBM Docs was translated automatically with machine translation. To take advantage of this, I rewrote the pages in DITA with extensive conkeyref reuse and a custom DITA XSLT override, supported in the build. It’s arguable which method is easier to maintain, YAML or DITA, but the content strategists were satisfied with the change regardless.

Design with Hugo

Design with Hugo on mobile

Design with DITA XSLT