technical documentation
optical networking hardware and software

TABLE OF CONTENTS

case study

OVERVIEW

brief

process

DELIVERABLES

videos

links

OVERVIEW

Client

-  XKL

Location

-  Seattle, WA

Industry

-  Telecommunications

COMPANY PROFILE

-  Privately owned by Cisco Systems co-founder Len Bosack

Technologies

-  Hardware development
-  Software development
-  Optical networking
-  Circuit-board design
-  Mechanical engineering

Product(s)

-  DarkStar Optical Networking System
-  TOAD operating system
-  Xalion optical router (R&D)

Projects / features / deliverables

-  Tools integration
-  Structured authoring template and EDD development
-  Technical documentation
-  Technical diagrams
-  White papers
-  RFPs

duration / date

-  22 months / 2009-2011

background

This case study highlights technical documentation for XKL's flagship product line, the DarkStar optical networking system. The system comprises both hardware and software.

For those who do not know much about optical networking, fiber-optic cable is essentially glass thread. Optical transport systems convert data into light and pulse it through this fiber or glass thread with lasers, allowing for incredible data throughput and speed.

The extreme levels of tech geekery at this company are not to be outdone. To that point, technologists here could only be referred to as computer scientists, never engineers. This foundation can be attributed to the deep nerd roots brought by the company's sole owner, Len Boscack, co-founder of Cisco Systems, a man affectionately known as a geek godfather who helped usher in the modern era of technology. In fact, many of the employees at the company were first-generation computer scientists who cut their teeth on technology with him at Stanford University, Digital Equipment Corporation (DEC), and Cisco Systems in the 1960s and 1970s. Among my colleagues were the men who invented spell check and a father of Ethernet technology. It was a great experience to work with these gentlemen.

Initially, I was hired for a three-month contract. I was tasked with updating technical documentation for the company's flagship DarkStar product line. 

problem

The previous writer had suddenly left the company late in a release cycle. The pressure is always on in software releases. But with only weeks before release, the pressure was extremely high.

The director who hired me was unhappy with the quality existing documentation. The DarkStar product line ran on one-year release cycles, but the previous writer claimed documentation work was a full-time job. Getting the job done had been a constant ordeal. The company made a quality product but the documentation did not match the performance or reputation of the product. 

solution

The first order of business was finishing the documentation for the first release. After that was accomplished, I turned my attention to the long-term vision of documentation at the company. 

Over the course of my tenure, I completely revamped publishing toolsets, anchoring the company in Structured FrameMaker. I also created new publishing processes, integrated with product development, where none had existed. This change management was a radically different path for the company but one that was well received.

These changes coupled with better work ethic meant that document production could be managed in shorter release windows. 

Challenges

There were serious problems with the quality of the documentation I inherited. It was incomplete and riddled with technical and orthographic errors.

Documentation was spread across two problematic toolsets: LaTeX and Adobe InDesign. LaTeX is an outdated, markup-language, publishing tool. It was originally released in 1985 and has undergone little evolution since then. InDesign is a visually oriented publishing tool, better suited to graphic-oriented layout, such as posters, catalogs, and magazines. Neither tool was appropriate for publishing large, technical, documentation sets. 

Sometimes nerd ideology worked against me, especially with tool management. Among other rules, all Microsoft products were prohibited within the enterprise and the shop ran strictly on open-source software and freeware.  

Outcome 

Tool and process improvements, combined with honest scoping, reduced the documentation cycle from one year to three months, a job that could be managed in a window just prior to release. The reduction in production time helped support a move to six-month software release cycles.

Once these improvements were rooted, it allowed a new focus on content quality and other content-related projects, things that had been ignored or neglected for years. The marketing collateral and RFPs I produced made significant contributions to sales.

I often preach to non-believers that content is design. This project is a perfect albeit unusual example of that maxim. When your product is a 1U, rackmount unit with several primitive buttons, and everything else is managed remotely on the command line, largely, the documentation becomes the user experience. Both engineers and end users responded positively to the significant changes in the documentation.

Based on my success during my initial, three-month assignment, my contract was extended with an open-ended arrangement. I went on to consult at XKL for nearly two years.

discovery

My initial work on my first release served a dual purpose. Beyond bringing the documentation into sync with the software release, it also gave me the opportunity to familiarize myself with content, tools, and processes. I would later use this discovery as the cornerstone in engineering new processes and introducing new software tools to the enterprise.

tools research and strategy

I was intimately familiar with InDesign and knew immediately that this application was not appropriate as a tool for managing large, technical documentation sets. I considered alternatives, but ultimately settled upon Structured FrameMaker. It was well suited for the size and complexity of the hardware and software documentation, but the embedded style and hierarchical conventions in structured authoring were also perfect for an environment that had seen high turnover with writers, yet needed to retain consistency in content and style.

template prototyping and development

Once the decision to move to Structured FrameMaker had been made, I began creating a list of requirements and benchmarking documentation from other IT vendors. Once I established clear goals, I began developing our templates. Before this work, I had not used Structured FrameMaker, but was conceptually familiar with structured authoring. During this project, I taught myself structured authoring and development on the fly. Armed with only the Adobe FrameMaker Developer's Guide and user forums as my reference, I wrote a custom EDD and DTD.

tools migration 

Once the FrameMaker templates were completed, all of the content authored in LaTex and InDesign had to be migrated to the new authoring tool. This work encompassed several thousand pages of documentation and took months to finish.

process engineering and tools integration

Once the documentation had undergone radical edits to improve content quality, and the new Structured FrameMaker templates were in place, I turned my attention to improving publishing process. The engineers had been passing around a single hard copy of the documentation and making edits manually for every release. I introduced PDF-based reviews and incorporated new processes with the existing Bugzilla system to create a streamlined workflow. It decreased production time by months while bolstering content quality.