Single Source Topic Based Authoring

Team Work
CSS and HTML
Single Source Authoring
Topic-Based Templates
Technical Writing and Editing

About This Project

I worked on a single source project for a hypothetical client, Zen 4 System, with two of my teammates—Chris Fowler and Jillian Garcia. We used MS Teams for our communications, web meetings, and its Share Point feature to manage and edit excel spreadsheets and word documents. We were tasked with producing proof of concept for the client. To accomplish that, we had two tasks:

Write topic-based and structured technical content components in MadCap Flare
Publish single source technical content in print and on the web

Background on the Project

The content we worked on consisted of two system guides—Hardware and Software Configuration—for an enterprise-class server called the Zen4. We had access to the two PDF guides (Software Installation Guide and System Hardware Guide) which we used as a reference to weed out the duplicate content, and to figure out which files were relevant to our project.

View the Hardware PDF Output

View the Software PDF Output

Planning Stage

Create a Team Charter

We codified our roles and responsibilities, and our communication plan in the team charter during an online teams meeting. Everyone filled out their roles and talked about their expectations for the project. I volunteered to be the team manager and throughout the project made sure my teammates were aware of tasks and deadlines.

Sort Through the Clutter

We started with an excel sheet of the two unstructured FrameMaker “book” files imported on MadCap Flare by the Tech Company. To make it easy to sort through the 193 files, our team focussed on the first chapter and the appendices of the two guides. We then sorted the content based on the following DITA Topic types with Heretto’s Information Model as the reference:

Task: Procedural information that helps users accomplish a goal

Reference: Reference information that users can refer to when completing tasks

Concept: Information that helps users understand information about an idea or feature

Once we categorized all the chapter 1 files and appendices from both the guides, we inserted metadata and keywords in the topic files to create a searchable knowledge base website.

Choose Keywords and Metadata for the Assigned Flare Files

Each of us assigned ourselves 1/3rd portion of the files, opened them in Flare and looked at the content. We assigned keywords and metadata for every file we were planning to work on. We chose some of the keywords based on how frequently they appeared in the topic or throughout the manual.

For example, the Zen 4 System and Architectural
Overview topic file has the following keywords:

Zen4

Resource modules

AMD Opteron

Low-latency access

Q-Series system modules

Ethernet Network Modules

Fibre Channel Modules

Application Service Modules

We decided to use author tags and short description tags for our metadata to save time during the content creation process, and short descriptions to help authors contextualize information.

Execution of Single Source Project

Structure Content Based on the Topic Templates

Before we started edits on the Flare files, I created a Team CJJ (first letter of team member’s names) folder to isolate and better control our edited files. During a Teams meeting we identified a lot of duplicate content in both the guides and the appendices. Our solution was to modify the duplicate files and use the revised content for all three output files thus fulfilling the single source requirement of the project. This modification of duplicate files helped to avoid repeating or overlapping information.

For example, we modified the Technical-Overview file from the Software guide, which included the same content as the hardware guide. The Technical-Overview file was then used for both the print guides and the HTML 5 output.

Create New Topic from Larger Topic Files for Content Management and Single Source Authoring

To conform to the brief of a single-source project, we broke larger topic files into smaller topics. This made it easier to customize output builds for different targets by adding or deleting standalone topics. To do this, we processed the content and arranged information in a way that made sense from a user’s point of view.

Below is an example of how Fibre-Channel-Module-FC file was separated into two topic files: Fibre-Channel-Module-FC and Fibre-Channel-Port.

Apply Design with Master CSS Style Sheet

Once all the files were edited and metadata and keywords tags appended, I modified the paragraph and first level headings in the Style Sheet for Print and HTML5 outputs. For HTML builds, I modified Heading 1 to a sans serif font (Calibri) and a 125% font size in bold. For the two print builds, I used a serif font (Times New Roman) and a 125% font size in bold. The paragraph font was modified accordingly with sans serif for HTML and serif for print output. The larger font size helped increase legibility of the paragraph text and the bold font of the heading emphasized and distinguished it from the body text.

Below is a screenshot of the CSS Style Sheet:

Consolidate the Edited Files and Create Table of Contents for the Three Targets

The file consolidation was relatively easy since I had created a separate folder for our team’s edited files in Flare. Once everyone’s edited files were added to the Team CJJ folder—divided into subfolders for Hardware, Software, and HTML5 targets—I created a unique topic and inserted a TOC proxy into it for the three targets.

The table of contents in Flare was built by dragging and dropping files from the Source Content Explorer section of Flare into the Project Organizer section. Here, I had built three TOCs—one for HTML and two for the print guides—Hardware and Software.

Here is a screenshot of the three TOCs:

Create a Customer Support section for HTML5 Output

While building the TOC, Chris and I realized that instead of creating appendices for the HTML target, we could isolate and consolidate some of the relevant hardware and software guide appendices files under Customer Support section in the TOC. This way, a customer looking for information about a particular topic, for example warranty information or ordering replacement parts or spares, could find it under the appropriate heading instead of sifting through the two appendices.

Here is a screenshot of the Customer Support Section in the HTML target:

Final Output Delivered

As a team, we designed three target publications—HTML website and two print PDFs—using HTML and CSS. The three target publications that we designed were:

A print Zen4 installation guide as a PDF
A print Zen4 configuration guide as a PDF
A Zen4 knowledgebase website as HTML 5

As a team, we also wrote a proof of concept cover letter to the client.

Read Proof of Concept Cover Letter

KEY TAKEAWAYS

Created three PDFs, each with a cover page and table of contents.
Reused content in the three builds by repeated use of topics in all three outputs.
Authored and organized topics in Flare/Central usage.
Met requirements for topics: appropriate size with DITA-like elements from our content model.
Exceeded requirements for keywords & meta-descriptions to support random searches in HTML5 target.
Created a master stylesheet and tweaked CSS instead of relying on formatting.
Used Teams as a collaboration tool and exhibited good teamwork through shared files and interactions.