Heavy Machinery Documentation Viewer

Spogen.ai helps teams create, manage, and use product documentation more intelligently. For this project, I redesigned its Documentation Viewer for heavy machinery.

The original HTML page made the manual available, but it did not make it usable in the field. I redesigned the experience around how people actually work with machinery: by task, visual context, and the relationships between parts and systems.

The goal was to make heavy machinery documentation easier to search, understand, and use in high-pressure work environments where users need fast and safe answers.

I led the end-to-end design of the Documentation Viewer.

My work included:

• Understanding the existing HTML manual and the Documentation Builder that generated it.

• Conducting contextual inquiry with an internal stakeholder experienced in machinery documentation workflows.

• Defining user needs for operators, maintenance technicians, and supervisors.

• Creating information architecture, wireframes, UI designs, and an interactive prototype.

• Running two rounds of usability testing and iterating based on observed behavior.

• Designing reusable patterns that could extend to Spogen’s AI Assistant and Documentation Builder.

What changed

• 5 of 5 usability tasks were completed successfully in the first round with two internal stakeholders.

• The System Graph was identified by the CTO as valuable enough to extend to Spogen’s AI Assistant and Documentation Builder.

• The procedure view was recognized for turning long manual content into clearer, task-based steps.

• Role-based filters were removed after testing showed that use-case filters were clearer and faster.

Potential business impact

• Faster time-to-answer for routine maintenance and troubleshooting.

• Reduced reliance on support teams for basic documentation questions.

• Safer execution of maintenance tasks through clearer procedures and visible safety context.

• A reusable system-navigation pattern across Spogen’s documentation products.

What still needs validation

• Field testing with operators and technicians using real machinery.

• Measurement of search success, time-to-answer, support-ticket reduction, and procedure-completion accuracy.

• Safety review of procedure order, warnings, and error-recovery paths with domain experts.

The existing HTML page rendered the manual, but it was not designed for how field work happens.

Heavy machinery documentation is long, technical, and safety-critical. Users do not open it to read a chapter from beginning to end. They open it because they need to complete a task: inspect a machine, diagnose a fault, replace a part, or verify that maintenance was performed correctly.

The original experience treated all users and all tasks the same.

Six structural problems

1. Search lacked intent. Results showed only a title and chapter number, so users could not tell whether a result was a procedure, troubleshooting guide, safety warning, or part reference.

2. Navigation was chapter-first. The manual’s structure did not match how users thought about the machine or their current task.

3. Long pages created disorientation. With 11 chapters and hundreds of sections, users could lose their place after scrolling, searching, or following a deep link.

4. Image callouts obscured the image. Detail cards covered the very visual information users needed to understand.

5. Related content was disconnected. Parts, procedures, videos, warnings, and subsystems were separated across the manual.

6. Procedures were not execution-ready. Long text blocks made it harder to follow steps safely, especially when users were working near the machine.

Who uses it

Before: A single HTML manual treated operators, technicians, and supervisors the same way. Users had to search through 11 chapters and hundreds of sections to find one safe procedure.

After: A task-based Documentation Viewer that lets users search by intent, scan visually, follow procedures step by step, and explore the machine as a connected system.

Evidence: 5/5 first-round task success; System Graph adopted across two other products.

The challenge was not only information density. It was designing for people using documentation under time pressure, in physically demanding environments, where an unclear step can create safety risk.

1. Audit the existing experience
   I audited the HTML Documentation Viewer and conducted a usability heuristic evaluation to identify navigation, search, hierarchy, and safety-related friction.

   
   

2. Understand user needs
   I created AI-assisted personas for operators, maintenance technicians, and supervisors to understand their goals, workflows, and documentation needs. I validated these needs through contextual inquiry with an internal stakeholder.

   
   

3. Define the experience principles
   I translated the findings into fast wayfinding, safe execution, system-based navigation, and progressive disclosure.

   
   

4. Design one problem at a time
   I addressed search context, navigation orientation, image callouts, procedure execution, and system relationships separately. I created wireframes and solved one UX problem at a time, using Claude and Codex to support research, wireframing, and code prototyping.

   
   

5. Test and iterate
   I tested the first prototype with two internal stakeholders and refined the design based on observed behavior.

   
   

6. Design for reuse
   In the second iteration, I also studied the Documentation Builder platform that generated the HTML page, and the AI Assistant experience. This helped me think beyond one viewer and design features that could be reused across products.

Before a single wireframe was drawn, four principles shaped every decision that followed.

• Fast wayfinding

  Find the right section quickly. Every feature reduces the number of steps between intent and content.

  
  
  

• Keep users oriented

  Whether users arrive through search, a deep link, or the sidebar, they should always know where they are and how to return.

  
  
  

• Make safety impossible to miss

  Warnings, required tools, and critical steps should remain visible during execution, not hidden inside long text.

  
  
  

• Show the machine as a system

  Reveal complexity only when needed. Overview first, detail on demand, from the sidebar to the System Graph nodes.

• Reveal complexity gradually

  Show the overview first. Let users open detail only when they need it.

After the first prototype, I tested the design with two internal stakeholders. Based on their feedback, I refined the navigation, filters, image callouts, and graph interactions.

In the second iteration, I also studied the Documentation Builder platform that generated the HTML page, and the AI Assistant experience. This helped me think beyond one viewer and design features that could be reused across products.

1. Use-case filters work better than role filters when roles overlap.
   I initially designed filters for both roles and use cases. Testing showed that role names created confusion because users saw themselves in more than one role. Use cases such as repair, maintenance, and troubleshooting—were clearer and faster.

   
   

2. Shadowing changes what you design.
   Reading about users is different from watching them work. The System Graph came from observing how an internal stakeholder moved between parts, procedures, and related content—not from an assumption made during initial research.

   
   

3. Solve one problem at a time.
   Designing each UX failure separately kept decisions traceable and made usability findings easier to interpret.

   
   

4. A strong interaction needs operational boundaries.
   The System Graph was compelling, but it also needed rules for empty states, dense systems, reset behavior, and missing content. A feature is not finished when it works; it is finished when it fails safely and clearly.