MadCap Software LogoLeft Quotation MarkRight Quotation Mark

Carnegie Mellon University Instructors Use MadCap Flare to Teach Software Documentation Best Practices

Case Study Icon

Carnegie Mellon University

Pittsburgh, PA

Industry:

  • Education

Goals:

  • Provide hands-on experience with authoring software
  • Apply best practices, including topic-based authoring, single-source publishing, and DITA content publishing
  • Support the XML standard for content

Solutions:

  • MadCap Flare native XML content authoring software

Benefits:

  • All students have been able to develop online Help, regardless of their technical expertise
  • Flare indexing and glossary features simplify online Help navigation
  • Flare provides easy way to understand topic-based authoring
"We looked at a number of tools, but Flare was the one that dove-tailed nicely with our needs."
Jennifer Ciroli | Carnegie Mellon University
"Flare has been an extremely valuable tool for giving our students real-world experience."
Tracey DePellegrin Connelly | Carnegie Mellon University

Carnegie Mellon University (CMU) is a global research university recognized for its world-class arts and technology programs and innovative leadership in education. The top-ranked university makes a strong commitment to offering advanced degrees that prepare students for the professional demands of today's businesses. This commitment extends to the CMU Master of Arts in Professional Writing (MAPW) curriculum and its Software Documentation class.

Adjunct instructors Tracey DePellegrin Connelly and Jennifer Ciroli co-teach the Software Documentation class, which combines lessons on the concepts behind creating and publishing software documentation with class projects that offer a practical application of those concepts. Since January 2009, they have used MadCap Flare, MadCap's flagship authoring software, to let students at all skill levels create online software documentation that incorporates state-of-the-art practices, such as topic-based authoring and single-source publishing.

"In the past, students mocked up their online Help in HTML. It was extremely labor-intensive, and it didn't give them the practical experience of using an authoring tool," said Tracey DePellegrin Connelly. "With Flare, the difference is night and day between what they were doing before and what they are now able to learn. It's been an extremely valuable tool for giving our students real-world experience."

New Authoring Concepts Require New Software

The catalyst for moving to Flare was a major update to the Software Documentation class lesson plan. In 2008, Ms. DePellegrin Connelly and Ms. Ciroli identified the need to add new documentation practices rapidly being adopted by businesses. These included content development based on the Darwin Information Typing Architecture (DITA) standard, topic-based authoring, and single-source publishing.

"When we overhauled the class, we knew our students would need to start a project in DITA using the oXygen XML editor and then create a set of topics that could be single-sourced and re-used for online Help," recalled Jennifer Ciroli. "We looked at a number of tools, but Flare was the one that dovetailed nicely with our needs. With its native XML architecture, single-sourcing, and topic-based paradigm, Flare was a natural fit."

The Spring 2009 class was the first to use Flare in conjunction with the new lesson plan. Students had two major assignments. The first was a software user guide with a cohesive set of task-oriented topics that could stand on their own and work together; it could be published as either a PDF or online information center. The second was an online Help project for which students were required to determine which topics they could use from the user guide, what new topics they needed to add, how to present and organize the information, and how to make it searchable.

Bringing Best Practices to Life

"It can be hard to grasp the separation of content and formatting within a structured authoring environment if you are used to working with word processing and authoring packages where the formatting is applied directly to the content," said Ms. Ciroli. "Flare did a nice job of bridging that gap. Our students liked that they didn't have to worry about formatting, as well as how easy it was to set up the online Help navigation using the indexing and glossary features in Flare. Whether they were technically savvy or not, all the students could get the output they needed."

"Having a program where I could take the step from concept to implementation was crucial for my current position," said Julian Cantella, a student of the CMU Software Documentation class now working with a large high-tech company as a student co-op. "Using Flare in the class helped me to prepare professionally. I am regularly publishing documentation in different formats, including PDFs and online content, and I use topic-based authoring every day."

The Spring 2009 Software Documentation class used Flare 4.0, which like other authoring tools required some manual steps to import and transform DITA content. As a result, the students had to manually edit their DITA content in XML to import it into Flare. Beginning with the Spring 2010 class, Ms. DePellegrin Connelly and Ms. Ciroli plan to upgrade to Flare 5.0. Launched in June 2009, Flare 5.0 is the first authoring software to support transformation and publishing from DITA without requiring Java development or third-party toolkits, such as Open Toolkit.

"The DITA conversion process with Flare 4.0 gave students a real-world experience, but the ability to automate this process with Flare 5.0–and then go into any format needed–is where the future is headed," said Ms. Ciroli. Ms. DePellegrin Connelly added, "Most of our students go onto software documentation jobs, so working with software like Flare is a good investment."

In the Spring 2010 class, additional lab time is being offered to allow students to take advantage of all the software's functionality.