Geeks With Blogs

Technical Writing by Mark Metcalfe, Publications Professional
Ektron product documentation puts a new twist on topic-based information, creating a streamlined, single-sourced, multi-formatted, topic-based information delivery system.

Traditional topic-based documentation links discrete chunks in a chain of related-but-often-isolated, granular bits. Ektron groups the discrete relations into parent topics. The output is compressed in accordion fashion using the drop-down feature that is available in the MadCap Flare authoring tool. Some parent topics are as large as 50 PDF pages (and more) containing dozens of children topics but are displayed in a single help topic while providing the reader with easy access to all related information. 

The accordion method improves the user experience by letting readers scan and access discrete topics on one help screen, without losing context by jumping from topic to topic. Drop-downs optimize information so that differently skilled users can scan essential information, and open the information they need more quickly. For example, Ektron hides images, code examples, field descriptions, and other information that can slow down an expert user. Each user at every skill level gets the right amount of information, easily expanding on it with a click when more is needed or wanted.

A by-product of taking this approach resulted in a huge savings in content file maintenance. Instead of managing many hundreds of small, discrete topic files, we merged files into parent topics, thereby reducing the number of content source files we needed to manage by a staggering 60% or more.

That is not all! The accordion approach made our mobile format easy to navigate and "finger-friendly." (We also placed QR codes in the Web and PDF formats to make it easy for customers to scan and get the mobile-formatted documents on their hand-held smart devices.)

The Ektron Reference covers over 2100 (PDF) pages of information. We optimized source content for online and mobile consumption (by converting many tables to lists, for example) and that also has resulted in an even bigger savings in the PDF page count. Using conditions, we use a single-sourced project to generate Web (HTML5), and PDF documents for multiple releases. 

I'd love for you to have a look for yourself at the Ektron Product Documentation Page.

Mark Metcalfe
Posted on Thursday, February 21, 2013 9:58 AM topic-based , help , mobile | Back to top

Comments on this post: Topics on Steroids

No comments posted yet.
Your comment:
 (will show your gravatar)

Copyright © TechnicalWriting | Powered by: