68.3 August 2021

Innovation and Collaboration: From Lightweight DITA to mHealth Apps

In the May 2021 Technical Communication article, “Hashtag #TechComm: An Overview of Members, Networks, and Themes from 2016-2019,” Chris Lam made several important recommendations, including strategies to increase technical communication practitioner and academic collaborations. In discussing one such collaboration, Lam wrote, “Developed by Carlos Evia, Michael Priestley, and a committee of volunteers, lightweight DITA is an architecture that does not rely on any particular technology or language, including XML” (Evia & Priestley, 2016). To continue our conversation from the May issue and as a prelude to the excellent articles in this issue, I interviewed Michael Priestley, Lead Information Architect at IBM, and Carlos Evia, Professor of Communication, Associate Dean for Transdisciplinary Initiatives, and Chief Technology Officer in the College of Liberal Arts and Human Sciences at Virginia Tech, about their experiences with collaboration and innovation.

Miriam: Tell us about your academic-practitioner collaboration. What is Lightweight DITA and how was it developed?

Carlos: In order to define Lightweight DITA (LwDITA), we have to start with the Darwin Information Typing Architecture (DITA), which is “an XML-based architecture for authoring, producing, and delivering topic-oriented, information-typed content that can be reused and single-sourced in a variety of ways.” That is actually the official definition of the DITA open standard from its technical specification. Now, whereas DITA is based on XML, which is the acronym for the extensible markup language, LwDITA incorporates flexible markup options and allows authoring content in a subset of DITA’s XML elements and representations of those elements in HTML (hypertext markup language) and Markdown (a shorthand syntax for creating HTML).

One of the key features of LwDITA as an open standard in preparation is that all of its supported markup options are compatible with each other and with DITA. Therefore, members of a publications team can create content using DITA and LwDITA (in any of its markup options) and share and reuse sentences, paragraphs, and whole topics without conversion or translation.

Now, Michael can talk more about the origins of LwDITA (and DITA) because he has been with them since the beginning.

Michael: DITA was developed at IBM for our product (software and hardware) documentation needs. We developed a deliberately extensible architecture, based on modular content, collections, and inheritance, which was definitely influenced by my experiences as a writer and information architect for object-oriented developer tools. We contributed it to the Organization for the Advancement of Structured Information Standards (OASIS) in the hopes that community adoption would both protect and build on our investment. Twenty years later, we are still using DITA, and so are many, many other companies.

About a decade ago, though, there was a lot of concern about the future of DITA—its adoption curve was flattening, and people were looking at other (in some cases even older, like Markdown) technologies for authoring. So, we spent some time looking at where DITA adoption was failing—where there was a need for DITA from a capability perspective, but a failure to adopt for some other reason. There were two main reasons we ended up focused on:

1) Complexity—authors can be intimidated by the sheer number of elements, and options for their use. And while a company can create their own simplified DITA profile (and many companies have), doing so requires additional technical knowledge, and can inhibit content interchange.

2) Community investment in their existing standard-when an authoring community has already bought in to an authoring format—like Markdown or HTML authored in a web content management system—the barriers to shifting to another format are extremely high.

LwDITA became an opportunity to address both of those concerns at once: create a simplified vocabulary and architecture that could then be applied outside XML, starting with Markdown and HTML.

I shared a draft version of an HTML spec for LwDITA on Twitter, and Carlos reached out to me, and we’ve been partners on its development ever since.

Miriam: This year, I attended Adobe DITA World 2021, which included over 400 of the Fortune 500 companies. What types of organizations are currently using (or should be using) Lightweight DITA?

Michael: The Markdown flavor in particular is proving popular where content is authored primarily or in collaboration with developers. That’s probably the area where it’s taken off the most, but as Carlos says, the opportunities are wider than that, and we’re seeing case studies and adoption across a wide range of use cases.

Carlos: DITA has been associated with technical content primarily because of its origins at IBM. However, the DITA standard is used across organizations for all types of content and not exclusively for technical documentation. Actually, the forthcoming 2.0 version of the DITA standard separates its base topic structure from the technical content topic types (i.e. concept, task, and reference) that are traditionally associated with DITA. LwDITA shares that agnostic approach to content, and we have already seen preliminary implementations for marketing, procedural information, software and application programming interface (API) documentation, and many other forms of digital communication.

Miriam: The two of you wrote an article for Technical Communication, “Structured Authoring without XML: Evaluating Lightweight DITA for Technical Documentation,” which received a 2017 STC Frank R. Smith Award for Distinguished Journal Article. What recommendations do you have for practitioners and researchers in higher education who want to collaborate on projects or research articles but aren’t sure how to begin? What first steps can you recommend?

Carlos: Don’t be shy. I remember going to conferences like the STC Summit and meeting people from industry. I was pretty much in groups with my academic colleagues and reaching across the aisle to talk to vendors and people in industry was a little intimidating … but I started doing that. I even had the conscious idea of meeting at least one practitioner or vendor per conference. And then I started following them on social media channels.

The beginning of my collaborations with Michael was like that. I had been following him on Twitter for years because of his DITA work, but we had not met in person. I did know, however, many of his colleagues because of my explorations in conferences. And then one day I just emailed him and said “Hi, I looked at your Lightweight DITA idea and made a sample project. Do you want to see it and give me feedback?” and we have been working together since then.

Michael: What he said! Find people you want to collaborate with and reach out. The first part is finding those people—finding conferences with a good mix of backgrounds, or meetups—building bridges based on interest, rather than organizational category.

Miriam: How should we introduce DITA or Lightweight DITA to our students? Do you recommend stand-alone courses? If so, what kind? Undergraduate level, graduate-level, certificates? Also, what resources are available to learn or teach Lightweight DITA?

Michael: Totally going to defer to Carlos on this one.

Carlos: I have taught DITA and LwDITA in courses at the undergraduate and graduate levels in the Department of English and the School of Communication at Virginia Tech. I have seen how both undergraduate and graduate students benefit from learning concepts of topic-based authoring, content reuse, and multichannel publication. In my experience, I can say that one course is a good introduction but not enough to prepare students for careers in content operations based on DITA or LwDITA-like workflows. So, I would say that it depends on the curricular objective: if you want an introduction, then one course would work; but if you want true career preparation, then you need more than one course.

I think, based on conversations with colleagues in industry and academia as part of a research study that I am conducting with Rebekka Andersen, that probably our standard curricular approach to technical communication in the United States needs a shakeup. [Editor’s note: Rebekka Andersen and JoAnn Hackos’s article, “Practicing Technical Communicators’ Experiences with and Perspectives on Academic Publishing” appears in this issue of Technical Communication.] Many existing programs are built around publication: there’s the web course, the documentation course, the proposal course, the report course, etc. Contemporary approaches to technical content (and other forms of content) should emphasize audience analysis and process, but from a publication-agnostic perspective. The deliverables are built on demand from a well structured repository of topics, and DITA and LwDITA-based workflows enable that.

Regarding resources to learn and teach LwDITA, all the materials that we develop for OASIS are free. Of course, if you twist my arm, I can do a shameless promotion pitch for my book “Creating Intelligent Content with Lightweight DITA,” which documents the development of this proposed standard and also gives examples for teaching about it in technical communication courses.

In This Issue

The excellent case history, tutorial, and research articles in this issue demonstrate the importance of innovation and collaboration in technical communication. The articles discuss emerging research areas that are important for practitioners, researchers, teachers, and students. So, to introduce their excellent work, I asked the authors in this issue to answer the following questions: 1) What is new or innovative about this research? And 2) How might academics and practitioners collaborate to continue this important discussion?

In discussing their article, “Theory-to-Query: Developing a Corpus-Analysis Method Using Computer Programming, “ Cana Uluak Itchuaqiyaq, Nupoor Ranade, and Rebecca Walton responded,

This case history documents the development and use of the new theory-to-query method to transform theoretical approaches to computer code for analysis. This article also provides a strong rationale and context for the connection between citation practices and equity in academia.

Although interdisciplinarity has become a crucial component of TC work, more than often it remains focused towards the need for interdisciplinary skills and competencies. Our article argues that humans are a major component of organizational processes, and a focus on interdisciplinary collaborations across teams can not only utilize diverse skills, but also boost conscious participation in problem solving through articulation and other communication practices in practitioner communities. The Theory-to-Query workflow demonstrates how this can be achieved in both academic and practitioner workspaces.

In discussing the importance of innovation and collaboration in

“Practicing Technical Communicators’ Experiences with and Perspectives on Academic Publishing,” Rebekka Andersen and JoAnn Hackos wrote,

Drawing from perspectives shared by 187 practicing technical communicators, this study describes concrete ways in which academic research in the field can reach and impact much wider audiences, particularly TC stakeholders who are well positioned to apply research results and help shape new research questions and projects. The study is the first to examine practitioner experiences with and perspectives on academic research since Beard, Williams, and Doheny-Farina (1989) conducted their survey of practitioner experiences and perspectives.

We offer several suggestions for how academics and practitioners can continue this important discussion in our article conclusion. There, we specifically address how journals and professional organizations might better promote and increase access to published research and how authors and journals might increase the relevance, value, and accessibility of practice-oriented research for non-academic readers. We offer practitioners specific suggestions, too, such as volunteering work sites, proposing research questions and studies needed, and serving on journal reviewer boards.

Scott Mogull, when reflecting on the role of innovation and collaboration in his article, “Developing Technical Videos: Genres (or “Templates”) for Video Planning, Storyboarding, Scriptwriting, and Production” wrote,

This article synthesizes information throughout the technical communication literature on video development, with a focus on providing an organized and cohesive guide for research-informed practice. This article provides distinction between nine categories of different types of technical videos and introduces four genres for planning and writing videos in industry. The goal of this article is to provide a resource focusing on the written genres involved in the production of videos in industry.

Academics and practitioners may continue this discussion by providing additional examples and analyses of the content and style of video scripts for each of the nine different categories of technical videos. Additionally, visual communicators may further contribute to the training and practice of communication through video by analysis of the visual channel of different categories of technical video. Visual communicators may also continue this discussion by providing further analysis and recommendations for dynamism and engagement of technical videos, which are noted challenges for technical writers new to the video medium.

In Brian C. Britt and Rebecca K. Britt’s reflection on the role of innovation and collaboration in their article, “Roles of Medium and Narrative Believability in Guided Mobile Tour Navigation,” they wrote,

Our research offers a unique perspective on users’ perceptions of tour narratives and the tour experience as a whole. As our study shows, even narratives that are obviously fictional, such as one led by a self-described “holographic tour guide,” can have profound effects on engagement with a guided mobile tour. This research benefitted from an innovative methodological framework, including the use of a survey instrument originally developed to predict the outcomes of legal proceedings, in order to yield novel findings about tour navigation efficacy and appreciation of the tour narrative itself.

Academics and practitioners would benefit from further exploring the narrative transportation that occurs during guided mobile tours. This would help them to identify pitfalls that can interrupt such transportation as well as technical communication techniques to enrich the tour experience without worsening users’ navigation. This can culminate in a set of best practices for developing guided mobile tours that utilize plausible narratives, leveraging practitioners’ perspective of the state-of-the-art in the field alongside academics’ observations of the effects that different media and communicative cues have on the user experience in various contexts.

When discussing innovation and collaboration in their article, “mHealth Apps and Usability: Using User-Generated Content to Explore Users’ Experiences with a Civilian First Responder App,” authors Candice A. Welhausen and Kristin Marie Bivens wrote,

In terms of promoting a practitioner-academic crossover, we use two common usability methods from technical communication–open card sorting and affinity diagramming–to analyze user-generated content (i.e, review comments). Through our qualitative approach, we merged these usability methods and leveraged them to analyze user-generated content (UGC), which is new.

Secondly, this methodology as well as the size of our dataset allowed us to identify detailed themes in users’ experiences with the app as well as focus on the aspects of those experiences that are important to users because review comments are voluntarily contributed. As such, we propose that technical communicators can find value in harvesting this information, which can save time and resources by (in some cases) eliminating and/or reducing the need for in-person user testing.

Further, the kinds of feedback that users’ provide in review comments might not be collected from traditional usability methods because these methods tend to use a more structured approach that usually seeks to solicit specific kinds of feedback from users. Toward this end, and as we state in the conclusion (citing Getto & Labriola, 2019, p. 386), our research aims to contribute to the move in the field toward foregrounding the role of users ‘as collaborators.’

Our project is a joint effort that engaged the PulsePoint foundation, our respective institutions of higher education, and we employed several research assistants, students at our institutions. As such, our multi-institutional collaboration initiated a crossover experience at the intersection in TC of practitioner and scholarly work.

By engaging in content analyses of UGC, we demonstrate how that analysis can be transformed into a tool for TC practitioners and also returned back to the community it comes from (i.e., the PulsePoint Foundation). For example, we presented this article’s project at the STC 2021 Summit, and we received feedback from practitioners about how they might potentially implement the heuristic (or elements of it) into their own TC work.

Furthermore, by reaching out to Pulse Point app developers, as we state in the article, to discuss the information we were collecting about their users, we also called developers’ attention to the importance of attending to audiences as developers create and modify their products. This action, too, emphasized ethical and responsible data management practices, which are a cornerstone of the field. As such, we have completed what we think is an ethical research cycle and behaved as ethical researchers.

In sum, by focusing on usability and because technical communication experts are primarily concerned with advocating for the needs of users, our project connects the interests of technical communication experts–both academics and practitioners–, app developers, and users, providing a path for forging more effective relationships among these groups.