the-journey How I teach: Writing with Digital Technologies

My focus in teaching "Writing with Digital Technologies" is to prepare students for successful careers in technical communication.

Aside from my consulting practice, I also teach a few university courses. One of these courses is about writing with digital technologies, covering tools and technologies that students need to be successful in the field.

I enjoy teaching "Writing with Digital Technologies" because it fits my background: I grew up writing with different desktop word processors, but switched to document preparation systems like LaTeX and nroff as an undergraduate student in the 1990s. I set up one of the first websites on the Internet and coded the entire website by hand using HTML, later leveraging HTML5 and CSS to adapt the website for a modern audience. I like to explore technical writing tools and technologies like Markdown and DITA. All of these are key topics in the course.

Tools and concepts

When I was first asked to teach this course, several years ago, I started by asking technical writers and other technical communicators about the tools and concepts they used every day in their work, what tools and technologies students should learn before they graduate. While tools vary by industry, the feedback from these working professionals indicated that students needed to have a working, hands-on understanding of the concepts used in those tools.

Organizations will teach new hires about the tools they use, but that job training is impossible if you don't know the basics of similar tools. For example, a new technical writer working on web content will need to use a web content management system (CMS). There are a million different web CMS products; the organization will teach you how to use the CMS they rely on. But that's an impossible task if the new hire doesn't understand the basics of HTML or website content organization.

Based on that feedback, I planned a course outline that taught students the essential concepts that served as the foundational concepts across different digital writing tools and technologies. I divided the topics across five modules:

Module 1 - Exploring tech literacyHTML and CSS, including the basics of "block" and "inline" elements. Students also formatted several technical documents using HTML and CSS.
Module 2 - Websites and source controlHow to manage projects using GitHub, and formatting a file in Markdown. Students also created mobile-enabled websites using GitHub Pages.
Module 3 - Extensible markup with XMLExtensible markup with XML. Students practiced by creating several XML documents, including an RSS feed.
Module 4 - Reusable content with DITAHow to reuse and remix content using DITA. Students used the 30-day free trial of Oxygen XML Editor to create DITA Concepts, Tasks, and References. We also explored DITAMap and DITA variables, and how to transform documents from DITA to a variety of different output formats.
Module 5 - Technologies and toolsHow to create EPUB files, and what is inside an EPUB file. Students also gained hands-on experience with other tools including LibreOffice Writer and explored collaboration in Google Docs.

An updated outline

I have continued to update this course outline every time I teach the course. This semester, I decided to rearrange the topics to make room in the schedule for more tools and technologies. While this was a good goal, I think the schedule moved too quickly for the students; students seemed to struggle with learning a new topic every week. The class meets twice a week, with assignments due the following Sunday:

Week 1How to use Visual Studio CodeA gentle introduction to HTML (block and inline elements)Assignment: Evaluate their current skills in writing tools and technologies
Week 2Basic HTML: <h1>, <p>, <ul>, <strong>, <em>, and other block and inline elementsHTML 5: <header>, <nav>, <main>, <footer>, and other semantic elements.Assignment: Format a how-to article in HTML
Week 3Basic CSS and linking to a stylesheetCSS 3 and responsive web designAssignment: Update the how-to article to use stylesheets
Week 4Introduction to projects in GitHubIntroduction to MarkdownAssignment: Create their own GitHub project and write a file
Week 5Technical writing with MarkdownGitHub Pages and basics of GitHub collaborationAssignment: Format a how-to article in Markdown
Week 6XML as data, including how to write an RSS fileXML as markup, including the basics of DocBookAssignment: Format a how-to article in DocBook
Week 7Ebooks and EPUB, including the file structure of an EPUB archiveEPUB creation toolsAssignment: Format a how-to article as an EPUB
Week 8Introduction to DITA topics and content reuseHow to use Oxygen XML EditorAssignment: Create a DITA Concept file in Oxygen
Week 9DITA Concept files in OxygenDITAMap and DITA transformationsAssignment: Reuse several Concept files to create a PDF document
Week 10DITA Task files in OxygenHow to apply styles to a DITA transformationAssignment: Remix a Task file with the Concept files to create a new PDF document
Week 11DITA Reference files in OxygenConditional text with DITAValAssignment: Remix a Reference file with the DITA topics to create a new PDF document
Week 12Desktop publishing with ScribusLayers, objects, and colors in ScribusAssignment: Propose a final project topic
Week 13How to use LibreOffice WriterStyles and technical writing with LibreOfficeAssignment: Format a how-to article in LibreOffice
Week 14How to grow skills with a Personal Learning PlanCo-authoring with ChatGPT and AI toolsAssignment: Re-evaluate their skills in writing tools and technologies
Week 15(no class)(no class)Final project: Format a large document using one of the technologies we learned

I do not require students to create new content for the final project; instead, I encourage them to reuse a long document they wrote in another class. Since most students in this course are seniors, many chose to reformat their senior capstone paper.

The final project also includes a 500-word reflection where students discuss the writing technology they used for their formatting project, including the strengths and weaknesses of that tool for the task. For example, several students wanted to explore how to use DITA to create longer documents; while formatting a single 15-page document isn't the best demonstration of DITA's strengths, students might highlight what they learned by exploring DITA to format their document. Other students proposed reformatting a paper using LibreOffice, such as using chapters, left and right pages, and a different document size such as Crown Quarto or US Trade. Another common topic proposal was to turn a paper into a website, with a "landing" page and separate pages for the Introduction, Methods, Results, Discussion, and back matter such as Bibliography and Appendices.

Preparing students for their careers

I'll continue to update the course outline for the next time I teach this course. For example, I think we went too "deep" on certain topics including responsive web design; these are topics that technical writers need to know at a high level, but are usually the task of a specialist such as a web designer. Adjusting the topics and removing some "tangential" material will leave more room to explore key concepts in more detail.

But the overall course outline is strong. The topics emphasize the tools and technologies that are foundational in technical communication. By learning how to write HTML by hand, and how to build and organize their own websites, students are well prepared to create content in any web CMS. Learning how to write documents in Markdown also prepares students to write in Asciidoc or other "minimal markup" systems. GitHub is similar to other source code platforms like GitLab.

Similarly, learning how to work effectively in Visual Studio Code also prepares students to pick up Notepad++, Sublime Text, Eclipse, or any other editor that an employer prefers. The free trial for Oxygen XML Editor gives students the hands-on experience they need to learn content reuse with DITA, and provides a solid foundation to use other DITA and XML authoring tools like Fonto or Framemaker. And learning how to leverage styles in LibreOffice prepares students to create technical documents using any mature desktop word processor.

My focus in teaching "Writing with Digital Technologies" is to prepare students for successful careers in technical communication. Students gain hands-on experience not just with specific tools, but they learn how to put those concepts into practice anywhere.