โ† Selected work

Software AG, through the merger with IBM

CONTENT SYSTEMS 8 ACCESSIBILITY

Documentation restructure post- merger: rebuilding information architecture for scannability

Documentation restructure post- merger: rebuilding information architecture for scannability

ROLE

Content Designer/ UX Writer

compANY

Software AG, through the merger with IBM

SCOPE

webMethods suite documentation

year

1 month

โ†˜ BRIEF

Problem

When Software AG merged with IBM, I inherited two sets of documentation, written by two companies. Software AG's docs were organized around how the engineering teams had built the product. IBM's followed its own conventions. Neither was wrong on its own, but stitched together into one product library they gave users two different logics.

Users told us they could not find things. I audited the whole set, rebuilt it around the way people actually do the work, and got four very different teams to sign off on it.

The feedback and support tickets kept coming back to the same six issues:



  1. Duplicated topics


The same topic showed up in two or three places, each explained a bit differently. People had no idea which version to trust.



  1. Buried content


Useful pages sat four to five levels deep, under headings that made sense to whoever wrote them and nobody else.


  1. Mixed content types


Concepts, steps, and reference material were packed into the same blocks. If you only wanted the steps, you had to read everything else first.



  1. No troubleshooting guides


When something broke halfway through a tutorial, there was nowhere to go. People either filed a ticket or gave up.

  1. No inclusive terms


Outdated terms like master/slave and whitelist/blacklist were still over all the docs.

  1. Harder searchability


Related concepts were scattered, so search results led people to fragments of an answer instead of the whole thing.


Honestly, most of these problems existed before the merger. The merger just made all of them worse at the same time, and it made them impossible to ignore.

โ†˜ APPROACH

โ†˜ APPROACH

Process

How I figured out what was actually wrong

"The docs are hard to use" isn't something you can fix. So I started with a content audit.

I went through the API Gateway guides page by page and logged four things for each one: what it covered, where it lived, how deep it was nested, how easy the instructions were to follow, and whether another page already said the same thing.

That spreadsheet turned a vague complaint into a list of specific problems I could point at. It also changed how my stakeholder conversations went. I could show them that a single configuration topic existed in three places, or that a tutorial users relied on was five clicks deep

The rules I rebuilt it with

Once the audit was done, I wrote down a handful of rules so every decision after that point had something to check against:

  1. Organize by process, not by owner: Topics follow the order people actually do the work in, that is, get started, administer, use, promote, upgrade. Which team or which company wrote the page doesn't matter to the reader.


  2. Three levels at maximum: If a topic needs a fourth level to find a home, the structure above it is wrong.


  3. Say it once, link to it everywhere else: Every topic gets one canonical page. Other pages point to it instead of re-explaining it.


  4. Put help where people get stuck: Troubleshooting lives right after the task it supports, not in a separate corner of the site.


  5. Write for everyone: Inclusive, accessible terminology by default, in the documentation and in product copy.


Who I worked with

Each group knew something about the docs that I didn't, and each one also had limits I had to design around.


Developers


Told me which technical constraints were fixed and which had some give. That kept me from designing a structure the platform couldn't support.


Leadership


Needed new structure to scale across the full webMethods suite and roll out without disrupting active documentation work.

Designers


Turned the hierarchy into navigation that actually looked and felt coherent, so the UI backed up the structures instead of working against it.

Support teams


Knew from real tickets exactly where users got stuck. Most of the troubleshooting sections came straight out of those conversations.



The biggest constraint: The platform's URL and content-management structure couldn't change without a lot of engineering effort. So, I had to fit the new architecture inside the existing system. Instead of new URLs, removed pages redirect to their canonical topic.


Getting everyone to agree took some back and forth. What helped most was the audit. It is hard to argue for keeping three copies of the same page when they're sitting next to each other in a spreadsheet.


โ†˜ SOLUTION

โ†˜ SOLUTION

Before and after structure

What I found and what I changed


What I found
What I did about it

Main guides like Administering API Gateway and Using API Gateway had no links to their own subsections. You had to open the sidebar and dig.

I added subsection links to each main guide, so people can see what's inside and jump straight to it.

Most concepts were hard to find and weren't grouped with related ones. That confused readers and made search a lot less useful.

I restructured the entire guide around process, so related topics sit together in the order people need them.

A lot of topics were repeated across guides, often with small differences.

I removed the repeats and linked to the original topic instead. That simplified the docs, cut the word count, and gave readers fewer versions to choose between, which meant less decision fatigue.

Each guide had multiple levels of nested navigation, and some went four or five deep.

I limited navigation to three levels everywhere.

Old, non-inclusive terms were still in use throughout the docs.

I introduced inclusive language and replaced the old terms with accessible, inclusive ones. For example, master/slave became primary/replica, and whitelist became allowlist.

Users kept running into small issues and errors while following the user guides and getting-started tutorials

I added a troubleshooting section after each tutorial, so the fix is right there when something goes wrong.


The difference goes deeper than labels. Someone new lands in Getting Started and finds a troubleshooting section right after the tutorial they're following. Someone running the product day to day goes to Administering and sees every subsection up front. Every top-level heading now answers a question a user might actually have.

The "before" side is a simplified reconstruction. I didn't capture screenshots of the old hierarchy before it was retired, so I've rebuilt the shape of it from memory. The "after" side reflects the live IBM webMethods API Gateway docs.

The shipped structure in the live IBM webMethods API Gateway documentation.

Result

โ†˜ The outcome

โ†˜ The outcome

What changed

What changed

What changed

The thing I'm proudest of is that the structure stuck. Other teams across the webMethods suite started using it as the model for their own product docs, long after my part of the restructure was done.


  • Answers are faster to find. Every topic has one home, it's never more than three levels deep, and it sits next to the topics it belongs with.

  • Search works better. Grouping related concepts by process means search results land on complete answers, not fragments.

  • Less to read, less to decide. Cutting the repeated topics and 40+ redundant visuals made pages shorter and easier to scan.

  • Fewer dead ends. Troubleshooting after each tutorial gives users a next step when something breaks, and gives support a stable page to link to. Support pointed to fewer tickets about getting-started errors after launch.

  • Language that includes everyone. Outdated terms are gone, and the replacements became the default for new content.


What I would do differently:

We didn't have analytics set up before the restructure, so I can't give you a clean before-and-after number for time-to-answer or ticket volume. Next time, I'd set a baseline before touching anything: search success rate, time on page for the top tasks, and ticket counts by topic. The direction was obvious here. The numbers would have made it undeniable.

Get in touch

OPEN TO NEW OPPORTUNITIES

Let's talk about what's next.

Email

mahimashastryux@gmail.com

Get in touch

OPEN TO NEW OPPORTUNITIES

Let's talk about what's next.

Email

mahimashastryux@gmail.com

Get in touch

OPEN TO NEW OPPORTUNITIES

Find my work interesting? Let's talk

Email

mahimashastryux@gmail.com

MAHIMA SHASTRY

BANGALORE, INDIA

MAHIMA

Mahima. All rights reserved.

No templates were harmed in the process of making this portfolio

MAHIMA SHASTRY

BANGALORE, INDIA

MAHIMA

Mahima. All rights reserved.

No templates were harmed in the process of making this portfolio

MAHIMA SHASTRY

BANGALORE, INDIA

MAHIMA

Mahima. All rights reserved.

No templates were harmed in the process of making this portfolio

Create a free website with Framer, the website builder loved by startups, designers and agencies.