Single-Sourcing with MadCap Flare

Situation: For this hypothetical project, my team was tasked with creating a proof of concept for the Zen4 server manual guides. Their existing content was primarily delivered as two large, unstructured PDF documents: the System Hardware Guide and the Software Configuration Guide. The content, initially created in FrameMaker, was not structured for modern content management practices and needed to be reorganized into a more efficient and scalable system.

The proof of concept criteria included:

1. Single-Source Updates: The content should be easy to update once and automatically propagate across all related products and publications (both print and online).
2. Searchability: The online content must be more easily searchable, providing users a better way to find relevant information quickly.
3. Print Production: The content should be easily generated for print, ensuring consistency and a professional look for customers preferring printed materials.
4. Consistency for Translation: The content should be structured to facilitate easier translation into multiple languages, ensuring consistency across different regional versions.
5. Personalization: The print content should be personalized based on customer needs (e.g., hardware or software configurations).

The final deliverables were expected to include:

• PDF Guides for both Chapter 1 of hardware and software content (installation and configuration guides).
• A HTML5 Knowledge Base Website for searchable online content.

The success of this proof of concept would determine whether Content Rules would hire our team for future, larger-scale projects.

Task: Our task was to convert and structure the Zen4 content into a single-source content management solution using structured authoring principles with MadCap Flare. This would involve:

1. Converting unstructured content from FrameMaker into topic-based, modular content.
2. Applying structured authoring techniques using Jorsek’s Technical Content Development Guide (2021) to create a content model that supported single-source publishing for both print (PDF) and web (HTML5) formats.
3. Revising key content sections such as Chapter 1 and Appendices for both installation and configuration guides, ensuring content was structured, reusable, and easily updated.
4. Customizing content for personalization and ensuring it was prepared for future translation.
5. Delivering the final outputs: a PDF installation guide, a PDF configuration guide, and a fully searchable HTML5 knowledge base website.

Action: To meet the project requirements and deliver the proof of concept, our team followed a structured workflow:

• Learning and Preparation:
  
  • We began by completing tutorials on CSS for styling and MadCap Flare for content management. This was crucial for ensuring that we could structure and format the content appropriately.
  • We would discuss projects plans on Slack on a weekly basis. 
• Creating DITA Structured Templates 
  • We created structured authoring templates following Jorsek’s Technical Content Development Guide (2021). 
  • The following templates were made: Concept, Reference and Task.
  • These templates were made in order to implement into our project to provide consistent structure throughout. 
  • These templates were uploaded into MadCap Flare so that the whole team may use them for structuring topics. 
• The Reference template 
  
  

• Content Inventory Spreadsheet Model Development
  • We were provided and  followed a content inventory spreadsheet which included all the topic files to break down and categorize each topic into: hardware or software, DITA topic type, keywords, metadata and chapter. 
  • We split the topics into 3 sections where each person was responsible for identifying each category for the topics they were assigned. 
  • This allowed us to organize the Zen4 content accordingly and make it easier when transferring and implementing our formatted structure and information. 

• Content inventory spreadsheet
  
  
• Structured Authoring and Content Model Development:
  
  • We imported the unstructured FrameMaker files into MadCap Flare and began the process of restructuring the content.
  • We followed a content model for the Zen4 guides based on DITA-inspired templates. This model ensured that each topic had a consistent structure, using elements like headings, paragraphs, lists, and tables. This structure also made it easier to generate both print and web outputs, ensuring that each format would be consistent in design and content.

• Content Revision and Structuring:
  
  • We focused on key content sections such as Chapter 1 and the Appendices, which had the most overlap across the two original guides (installation and configuration).
  • Additionally, we added metadata such as keywords and meta descriptions to improve the searchability of the content, particularly for the HTML5 knowledge base.
• CSS Customization and Design:
  
  • We customized the CSS for both the print and HTML5 outputs.
  • For the PDF guides, we modified paragraph styles (e.g., increased font size for better legibility) and tweaked heading styles for clarity.
    1. For the HTML5 knowledge base, we modified the first-level heading style (H1) to enhance its visual appeal and make it more noticeable on the web.
  • We also ensured that the Table of Contents (TOC) for each target publication was properly structured, reflecting the new modular content.
• Testing and Publishing:
  
  • Once the content was revised, structured, and styled, we published the content in the following three formats:
    1. A PDF Zen4 Hardware Installation Guide.
    2. A PDF Zen4 Software Configuration Guide.
    3. An HTML5 Knowledge Base Website with searchable content.
  • We tested the outputs to ensure that the content was properly formatted, the links between topics worked correctly, and that the search functionality in the HTML5 site was efficient and accurate.

Result: By the end of the project, our team successfully delivered the following:

1. Print Publications (PDFs):
   
   • A Zen4 Hardware Installation Guide and Zen4 Software Configuration Guide, each with a revised Chapter 1, Appendices, and Table of Contents.
   • The guides were consistent in style and structure across both print formats and were easily updatable in the future.
2. Searchable HTML5 Knowledge Base:
   
   • A fully functional HTML5 knowledge base website, containing the same content as the print guides, with search functionality that allowed users to find relevant topics quickly.
3. Structured and Reusable Content:
   
   • The content was restructured through implementing templates using structured authoring principles. We used modular topics that could be reused, updated centrally, and repurposed for other projects. This made the content future-proof, scalable, and easier to manage.
4. Proof of Concept:
   
   • The final deliverables met all of the proof of concept criteria. The content was easy to update, searchable, consistent across formats, and could be personalized for different customers and versions.

Reflection: During this project, I focused on improving my skills in structured authoring and content management. I learned the importance of creating modular content that can be easily updated and reused across multiple formats, saving time and reducing the risk of errors. The project also helped me enhance my time management and collaboration skills, as we worked remotely and used Slack to stay coordinated. This experience will be invaluable for my future career, particularly in the field of technical communication, where structured content and single-source publishing are becoming industry standards.

Finished Deliverables:

PDFs

HTML5 Knowledge Base:

Zen4 Knowledge Base update