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

Carnegie Mellon University instructors are using MadCap Flare in their Software Documentation class. MadCap's flagship authoring software enables students at all skill levels to create online software documentation that incorporates state-of-the-art practices, such as topic-based authoring and single-source publishing.

The Software Documentation class is part of the Carnegie Mellon Master of Arts in Professional Writing (MAPW) curriculum. Co-led by adjunct instructors Tracey DePellegrin Connelly and Jennifer Ciroli, it combines lessons on the concepts behind creating and publishing software documentation with class projects that offer a practical application of those concepts.

"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."

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 teach students about the 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 both stand alone and work together; the guide could be published as either a PDF or online information center. The second was online Help, for which students were required to determine which topics to use from the user guide, what new topics to add, how to present and organize the information, and how to make it searchable... Focus Areas: BPEL | DITA | ebXML | IDtrust | OpenDocument | SAML | UBL | UDDI
OASIS sites: OASIS | Cover Pages | | AMQP | CGM Open | eGov | Emergency | IDtrust | LegalXML | Open CSA | OSLC | WS-I