Structured authoring techniques can be essential in teaching students effective methods of developing user documentation.
By Michael Opsteegh, Fellow
Technical and professional communication students can benefit from structured authoring methods. Using structured authoring methods, students learn to compose and arrange their content to make it more usable and accessible to their human readers. Of equal importance, students also learn to structure their content to make it more usable to their machine readers—the content management systems, search engines, chatbots, and generative AI platforms—that humans rely on to locate and serve information.
Like many tech comm instructors (Cleary 2020; Evia, Sharp, and Perez-Quiñones 2015; Gesteland 2020; Duin and Tham 2019; Batova et al. 2016), I use structured authoring to teach students user-documentation methods. This article describes the course I teach and how my students incorporate topic-based authoring and XML to develop more useable content.
Situating the Course and Its Students
In addition to working as a tech comm practitioner, I teach a senior-level “Manual Writing” course at a state university. Although the course title is somewhat anachronistic, the description and learning outcomes are broad enough to encompass new and emergent methods of user documentation.
Early in the semester, I warn students that the content and skills they will develop in this course are unlike those they have developed in other classes—even in their other tech comm courses. I say that I “warn” them because students enroll in the course with a wide range of writing and technical experiences.
Before they enter the Manual Writing course, students’ writing experiences are often limited to essays and research papers that are generally presented in a linear format, directed to a narrow audience (usually, an audience of one), and designed to be used once and then discarded. This kind of writing affords students many liberties in the rhetorical choices they make. So long as those choices result in a satisfactory grade, students have little need to care whether the language in their essays is accessible to other audiences or whether the content is navigable or reusable.
The skills and rhetorical liberties described above don’t translate well to developing user documentation. User documentation must be directed toward multiple audiences simultaneously. The content must also be concise, modular, reusable, capable of being rendered in multiple media, capable of being easily updated as products or services evolve over time, and capable of being easily translated.
Additionally, many students are reticent to view content separately from formatting, having gone their entire academic lives manually formatting documents as they composed them, and as McShane (2009, 77) puts it, “watching the groovy things Word can do.”
Second, as others have noted (Evia, Sharp, and Perez-Quiñones 2015; Gesteland 2020), most of my students are English or creative writing majors who choose to enroll in the professional writing certificate program in the hopes of improving their job prospects after graduating. They may have initially chosen a major they perceived wouldn’t be technically rigorous. Suffice to say, their experiences and comfort with technology varies greatly, with some students avoiding unfamiliar technology altogether.
Since students need to develop multiple skills while learning to develop useful and usable user documentation, I take a “layered literacies” (Cargile Cook 2002) approach to teaching tech comm classes. For example, I often layer the basic literacy of document design with the technological literacy of working with the Styles feature in Microsoft® Word. These two skills overlap nicely, and learning Styles in Word easily translates to other tools and technologies. So too, I layer the rhetorical literacy of topic-based authoring with the technological literacy of XML markup. I’ll discuss how these skills complement each other in the next sections.
Topic-Based Authoring
Early in the semester, we start talking about how users need frequent content on-ramps in the form of headings and bite-size chunks that fit their busy lives and scarce attention. Thinking in terms of chunks or modules helps students understand that readers access content seemingly randomly rather than reading help content linearly.
The three basic DITA information types—concepts, tasks, and references—provide a ready framework for thinking of how to separate different types of content into different modules. In class, I refer to information types as topic types to help students understand and remember the connection between these abstract categories and the modules they’re writing.
In structured authoring, every topic has a type, and every type has a convention for the order, form, and content of a topic (Baker 2013, 97). For example, a task topic requires a heading, often a short introduction for context, steps, maybe some feedback, and notes or warnings. This need for topics to conform to a structure is where the XML comes into play.
XML
The purpose of XML tagging is threefold. First, it’s an exercise whereby students identify the elements within their content. In high school English classes, students are often asked to use different colors to highlight their topic sentences, supporting evidence, and conclusions in an essay. This activity requires students to think about what they’ve put on the page, how elements relate to each other, and what purposes they serve. In this same way, applying semantically-relevant XML tags gives students a language in which to think and talk about what they’ve composed. And once they can articulate it, they can begin to understand it more clearly.
Second, XML forces students to think more intentionally about the organization of the content that they’re presenting to users separately from design. They begin to recognize that the rhetorical flexibility they had in writing essays is now counterbalanced by the requirement to conform to the XML schema.
Third, as the XML imposes structure and order on their own writing, they begin to see how XML can be used to standardize content production across large teams.
Following is the document type definition (DTD) that I give students to paste at the beginning of their XML files.
The DTD defines the order and structure of the document by defining every allowable element and enumerating what each element may contain. The first couple of lines declare the XML file and reference the CSS file that controls the display of the XML in a web browser.
However, if we look at one of the lines prefaced by !ELEMENT, we can see how the DTD enforces rules about the content. For example, the “topic” element must include a title, one or more lines of introduction, and may include steps or a bulleted list.
This DTD is rather rudimentary, and students dislike how restrictive it is. However, if I were to add more flexibility in the form of substeps, for example, the complexity of the DTD would become too cumbersome for most students. Since this assignment is intended only to introduce the concept of structured authoring to students, this simple DTD does the trick.
The Assignment
To help frame the project for the students, I describe a scenario in which they are a member of a large tech pubs team that publishes the same content in multiple outputs. We spend a few weeks on the project and approach it in two stages.
In the first stage, students are asked to draft a brief set of user documentation in a word processor. They may write on any subject, but they must focus on organizing the content into several tightly related task-based topics. Students are instructed to limit their writing to 40 steps arranged in 4–6 topics, so they must resist the urge to write lots of content and instead focus on structure. These limitations are helpful, too, to reduce the stress of later applying the XML markup.
After the students have drafted their content and exchanged feedback with their peers, I provide feedback on their drafts, particularly in areas where their content won’t fit the schema the DTD enforces. I find that taking the time to look at the drafts before the students begin tagging the document saves everyone a lot of stress later.
In the second stage, students add XML tags to their instructions using Visual Studio Code or a text editor of their choice. To begin, students must paste the DTD at the beginning of their file and then apply XML tags, based on the elements specified in the DTD, to every piece of content in their file.
After the document is tagged, students QA their work by opening the file in a web browser. This gives them the opportunity to review the content and see what happens if they’ve misidentified a piece of content.
Before they can submit the file for a grade, they must submit it to an online validation site to ensure their XML is well formed and valid. They must work through all the errors the validation site finds until all the errors are resolved. If a student submits an invalid XML file, I promptly return it with a hint about why it failed validation and ask the student to resubmit the corrected file.
While the students can use any text editor to tag their XML files, I use Oxygen XML Editor to view them. Oxygen has a reasonably priced academic license, it features a built-in validation tool, and it enables me to open the file in a web browser with one click.
Student Feedback
I’ve been assigning and refining this project for about five years. Students rarely mention the XML project in their course reviews. When they do, it’s often a sarcastic comment along the lines of, “this is a writing class, not a coding class.” However, when former students reach out to me on LinkedIn to share their work experiences, they frequently cite the XML project as one of the most valuable lessons they took from the class, because they were able to apply the concepts of structured authoring immediately to their work.
Conclusion
In my Manual Writing class, we talk a lot about DITA without actually mentioning DITA by name. This is intentional, because it allows the students to develop a rhetorical literacy of structured authoring and a technological literacy of XML markup without getting hung up on the esoteric aspects of DITA.
In this article, I have presented approaches and materials I’ve developed for my course. You are free to use them or adapt them for your own course. If you have questions about teaching tech comm courses through structured writing or want to share your own ideas, I’d love to hear from you.
References
Baker, Mark. 2013. Every Page Is Page One: Topic-Based Writing for Technical Communication and the Web. Laguna Hills: XML Press.
Batova, Tatiana, Rebekka Andersen, Carlos Evia, Matthew R. Sharp, and John Stewart. 2016. “Incorporating Component Content Management and Content Strategy into Technical Communication Curricula.” In Proceedings of the 34th ACM International Conference on the Design of Communication, 1–3. New York: ACM.
Cargile Cook, Kelli. 2002. “Layered Literacies: A Theoretical Frame for Technical Communication Pedagogy.” Technical Communication Quarterly 11, no. 1: 5–29.
Cleary, Yvonne. 2020. “Teaching Topic-Based Writing.” In Teaching Content Management in Technical and Professional Communication, edited by Tracy Bridgeford, 72–86. New York: Routledge.
Duin, Ann Hill, and Jason Chew Kit Tham. 2019. “Cultivating Code Literacy: Course Redesign through Advisory Board Engagement.” Communication Design Quarterly 6, no. 3: 44–58.
Evia, Carlos, Matthew R. Sharp, and Manuel A. Perez-Quiñones. 2015. “Teaching Structured Authoring and DITA through Rhetorical and Computational Thinking.” IEEE Transactions on Professional Communication 58, no. 3: 328–43.
Gesteland, Becky Jo. 2020. “Teaching Content Management with XML.” In Teaching Content Management in Technical and Professional Communication, edited by Tracy Bridgeford, 108–24. New York: Routledge.
McShane, Becky Jo Gesteland. 2009. “Why We Should Teach XML: An Argument for Technical Acuity.” In Content Management: Bridging the Gap between Theory and Practice, edited by George Pullman and Baotong Gu, 73–85. New York: Routledge.
Michael Opsteegh (michael.opsteegh@csulb.edu) has been a technical writer in the software and financial services industries since 2004. He is currently a senior technical writer for Eyefinity, which supports eyecare professionals with industry-leading software and services. He’s a lecturer in the professional writing program at California State University, Long Beach, and a PhD candidate at Texas Tech University. He holds a master’s degree in English and a certificate in technical and professional communication. He is also a Certified Technical Professional Communicator (CPTC).
