User-Centered Transformation

At Oracle, I transformed our authoring guide from a system-based reference into a user-centric resource organized around writers’ tasks and workflow. Using a modular, task-oriented approach, I restructured the content rewriting titles and meta descriptions in writers’ language. I also filled gaps in conceptual guidance (see Concept Development), giving writers the context they needed to use the system confidently and correctly. The result was an easy-to-scan table of contents and a page count reduction of over 20%, with more complete guidance and a clearer path to relevant information.

For the complete before and after guides, see Results.

Simplified Guide Navigation

I cut the top-level entries in the table of contents in half by grouping content into workflow categories. The easier-to-scan structure:

  • Helps writers find the topics and tasks they need faster.

  • Reduces the effort needed to scan the guide.

  • Shows how topics connect and where they fit.

BEFORE

1 Introduction to Oxygen XML Author and SDL Knowledge Center
2 Oxygen XML Author and SDL Knowledge Center Installation
3 Objects in SDL Knowledge Center
4 Objects in Local Storage
5 Publications
6 Maps
7 Topics
8 Elements and Attributes
9 Workflow: Releasing, Versioning, and Branching
*10 Accessibility
11 Legal Notices
12 Inline Text Formatting
13 Comments
14 Prefaces
15 Examples

16 Notes
17 Lists
18 Tasks, Procedures, and Steps
19 Images
20 Tables
21 Linking
22 Tabbed Interfaces
23 Footnotes
24 Indexes
25 Glossaries
26 Content Reuse
27 Content References
28 Conditions
29 Variables
30 Searching the SDL Repository
*31 Create Output for a Publication
**Index

*Content moved to different guides.
**Content removed.

AFTER

1 Learning the OAK Foundation and Oxygen basics
2 Installing and working with OAK Foundation and
Oxygen 27
3 Authoring in OAK Foundation
4 Inserting traditional book pieces
5 Working with content in publications
6 Developing topic content
7 Reusing content
8 Versioning content & managing the publication baseline
9 Searching for content in OAK Foundation
A Default preferences in Oxygen
B Frequently asked questions
C Schematron rules in Oxygen
D Troubleshooting
E XML refactoring

Clear, Task-Focused Labels

I rewrote titles and meta descriptions to reflect writers’ tasks in familiar language. Clear, task-focused titles help writers spot the topics they need, while brief descriptions explain what each topic covers. Together, they help writers choose the right guidance with less guesswork.

Task-Based Labels in Practice

This before-and-after comparison of the content reuse guidance shows how task-based organization and clear titles help writers find, understand, and use information faster.

BEFORE

  • Unclear relationships between reuse methods: Topic reuse is under content reuse, while content references, conditions, and variables are alongside it. The structure fails to show that all four are content reuse methods.

  • Isolated tasks without workflow context: Tasks appear at the same level without grouping or sequence, leaving writers to piece together the full process for each reuse method.

  • Low-value tasks: Separate topics for routine actions, such as “Edit a Conref,” repeat steps writers can often infer from creating objects. These topics are useful only when the actions need distinct guidance.

  • Mixed concepts and tasks: Writers need either context to learn or steps to act. Mixing concept (shown in italics) and task topics makes writers scan past background they may already know to find the instructions they need.

26 Content Reuse

Reuse a Topic in Another Publication
Reuse a Topic Within a Publication
Create a Unique Target ID with the resourceid Element
Content Reuse: Conrefs, Conditions, and Variables

27 Content References

Conrefs and Conref Libraries
Create a Conref Library
Set the Preference for Displaying Conrefs
Insert a Conref
Edit a Conref
Conrefs with Badges and Platform Restriction Conrefs
Insert a Conref with a Badge or a Platform Restriction Conref
View All the Conrefs in a Publication
Delete a Conref

28 Conditions

About Conditions
Simple Condition Expressions
Complex Condition Expressions
The Condition Builder Dialog Box
The Condition Context of a Publication
View the Allowed Conditions and Condition Values
Conditions Management
Select a Condition to Use in a Publication
Conditionalize an Entire Topic
Conditionalize Content Within a Topic
Conditionalize a Row in a Table
Create a Complex Condition Expression
Remove a Condition in Publication Manager
Remove a Condition in Oxygen XML Author

29 Variables

Variables and Variable Libraries
The XML Structure of a Variable
Variables in a Publication
Create a Variable Library
Add a Variable Library to a Publication
Insert a Variable in a Topic
View the Variable Values for a Publication
Find Variable References
Modify a Variable Definition
Delete a Variable Definition from a Library Topic

AFTER

  • Clear relationships between reuse methods: Topic reuse, content references, conditions, and variables are grouped under content reuse, making their shared purpose clear.

  • Complete workflows with supporting tasks: Each reuse method has an end-to-end process, with tasks grouped beneath it in the order writers need them.

  • Focused task guidance: Routine actions that need no distinct guidance are consolidated or omitted, reducing clutter while preserving essential steps and cautions.

  • Separate conceptual guidance: Content reuse concepts are grouped with other product concepts, giving writers a clear place to learn without getting in the way of finding task instructions.

7 Reusing content

Insert content references for content reuse

Create conref library topics
Add a conref library topic as a resource
Insert a content reference

Insert variables for content reuse

Create a set of variable library topics
Add a variable library topic as a resource
Insert a variable

Control which conditions to include in a publication

Define conditions for publications
Apply conditional settings to a publication
Remove conditional settings from a publication

Conditionalize content

Conditionalize an entire topic or submap
Conditionalize content within a topic
Conditionalize a row in a table

Control how conditions look when viewed in the Editor

Apply styles to conditional text when viewed in the Editor
Show conditional text styles or attributes in the Editor

Reuse topics in a publication

Conceptual Structure and Clarity

I grouped all product concepts in a dedicated section, separate from task instructions, to support two needs: learning how the system works and getting work done. Writers can find background when they need it or go straight to task steps without scanning past concepts they already know.

The concept hierarchy also shows how ideas relate, from broad subjects to specific methods. Building this structure helped me spot gaps and expand the conceptual guidance, giving writers a more complete understanding of the system.

Conceptual Labeling and Organization in Practice

This before-and-after comparison shows how clear conceptual titles and a logical hierarchy help writers find background information and understand how ideas relate. The revised structure also helped me identify gaps and build more complete conceptual guidance.

BEFORE

  • Vague conceptual labels: Titles don’t clearly describe what each topic covers, making it hard for writers to tell whether it answers their question.

  • Scattered and incomplete guidance: Content reuse concepts are spread across multiple locations, making it hard to see all available methods or compare them. Conceptual guidance on topic reuse is missing.

  • Assumed knowledge of reuse methods: The content doesn’t explain when or how to use each reuse method. This gap led writers to misuse them, causing problems during content migrations and system upgrades.

26 Content Reuse

Content Reuse: Conrefs, Conditions, and Variables

27 Content References

Conrefs and Conref Libraries
Conrefs with Badges and Platform Restriction Conrefs

28 Conditions

About Conditions
Simple Condition Expressions
Complex Condition Expressions
The Condition Builder Dialog Box
The Condition Context of a Publication
Conditions Management

29 Variables

Variables and Variable Libraries
The XML Structure of a Variable
Variables in a Publication

How content references enable the reuse of parts of a topic

How content references work and when to use them
How keys work in content references

How variables enable the reuse of varying phrases

How variables work and when to use them
How keys work in variables

How keys work in DITA 1.2

How conditions enable the reuse of content variations

Which conditional expressions can be defined and how they are evaluated
How the DITAVAL file controls which conditions to include
What the Conditions Subject Scheme map does

How to reuse topics

AFTER

  • Descriptive conceptual labels: Titles explain what each content reuse method does, such as enabling reuse of parts of a topic, helping writers find the answers they need.

  • Complete, comparable guidance: All reuse methods are grouped together, making it easy for writers to see their options, compare them, and choose the right method.

  • Clear purpose and use: Guidance explains when and how to use each method, with examples that help writers apply it correctly and avoid problems during migrations and upgrades.

Results

The redesign cut the top-level table of contents entries in half and reduced the guide from 269 to 197 pages, a 27% reduction, while expanding conceptual guidance. Workflow-based groups, clearer titles, and separate concept and task sections gave writers a more focused guide with clearer paths to both background information and task instructions. The complete guides below show the structure and content before and after the redesign.

BEFORE

AUTHORING WITH OXYGEN XML AUTHOR AND SDL KNOWLEDGE CENTER

The original guide covers the third-party DITA authoring system used at Oracle, with content organized primarily around tool and DITA features like local storage and tables.

AFTER

AUTHORING WITH OAK FOUNDATION AND OXYGEN

The redesigned guide supports covers Oracle Authoring Kit (OAK) Foundation, an internally developed content management tool integrated with Oxygen. It organizes DITA authoring guidance around writers’ workflows and tasks, with a dedicated section for product concepts.