MadCap Flare Single-Source Proof-of-Concept
In this single source proof-of-concept, as a team, we learned about component content management systems, topic-based authoring, and single-source publishing using product documentation on MadCap Flare.
Project Specifics
Semester
Fall 2021
8W2
-
TECM 5191
Role
Team Editor
Category
Assignment
Team
Cordell Johnson
Eryn Bing
Me
Background
Single-Source Proof-of-Concept
My team, fictionally subcontracted by Content Rules, created a proof-of-concept single-source solution in order to properly show how to organize and maintain different kinds of content from an enterprise-class server called Zen4, which was built by “Tech Company.”
Project Goals
Using the content we received from Tech Company, we needed to find a way to
-
update content once across all related products and publications
-
make content searchable online
-
produce print for those customers who want it
-
create consistency across the different content creators/approvers who own different parts of the related products
-
personalize print content for different customers and product versions when possible
Content Model
In order to figure out what we were working with, we created a macro-content model using Microsoft Excel to properly label what we had. We were given two PDFs, one is a system hardware guide and the other is a software configuration guide. For this proof-of-concept, we did the first chapter of each guide and one of each appendix (as there are multiple appendices in both guides).
A Portion of our Macro-Content Model on an Excel Spreadsheet
Using DITA standards, we organized our files by DITA topic type. We specifically used Task, Concept, and Reference as these categories fit into our files. For our keywords, we used the tags that were mentioned in each file. The metadata included where and what each file was; however, we only did this with the files that were from our set list of chapters. The highlighted row was to help us organize which files were included whereas, later in the list, it becomes more complicated.
Files and Templates
The files from the guides originally came from each subheader of each chapter or appendix. We after we created our content model, we then edited every single file to meet DITA standards. Some files were combined, rearranged, or grammatically changed to fit into each chapter or appendix. We even created templates to make sure that it all fits within the standards of each topic type. Below is an example of a file we changed. This file is a concept topic type, but it had too many subheaders that didn’t directly correlate to the main concept, so we separated them into their own individual files.
The Edited System and Architectura Concept Topic Type
CSS and Design Changes
For this project, we had to create three targets, a PDF for the software guide, a PDF for the hardware guide, and an HTML output for every file. We changed the CSS in order to make everything in these files consistent. We changed the styles for both the paragraph and headings.
Existing CSS File we Edited
Table of Contents (TOC) and Targets
After we edited the files for our targets, we then had to edit our files’ organization to fit each target. To give a better idea of what our TOC looks like, below is our TOC for the hardware guide.
Our TOC for the Hardware Guide
Our targets turned out well. We were able to organize our edited files into two PDFs and an HTML output. Below is a screenshot of what our HTML output looks like. Unlike a TOC, we had to put our files into a navigation bar at the top of the page.
Our HTML Output
Challenges and Thoughts
Challenges
To complete this project, my team and I had to learn how to use MadCap Flare and that comes with a steep learning curve. MadCap Flare has a sharing feature called “Central” that we all had to use to upload our local changes into a cloud, but my team and I were having trouble uploading.
I had experimented and searched online for different methods to save our work and I found one. I also explained, using visual cues through Microsoft TEAMS meetings and our group messaging system, how to save work onto the cloud and it worked multiple times despite both of my team members having completely differnet saving issues.
The files that we were given to work with also didn’t have proper labels for each CSS element, so we were estimating and checking to make sure our CSS changes actually changed the right element. For example, we had issues regarding our bullet points which appeared often in both guides. They weren't appearing and registering properly as bullet points in the HTML5 version or the PDFs. I did my research and edited each one while guiding my group on how to do the same
In the end, we were finally able to come up with proper targets that achieve their purpose.
Thoughts
I’ve always heard of DITA content management systems like MadCap Flare, but I never had the chance to use them. I’m glad I had the opportunity to learn how they work with this project. If I were to do anything different with this project, I would have changed more of the CSS and file names to better fit into DITA standards.
This project taught me a lot of how company-wide content management systems work and to properly maintain and edit them. I've had previous HTML and CSS coding experience from other projects and I'm glad I was able to use these skills to see a tangible product such as this single-source proof-of-concept.