Technical writing with open source software

Aside from my other work, I also teach a few university courses about technical writing. One class I like to teach is about writing with digital technologies where students learn how to use several popular tools that they might use in their careers. This course needs to cover a lot of ground in just 16 weeks, and we spend a few weeks learning how to be productive in each tool before we move on to the next topic.

It turns out that a lot of industry professionals use open source software or open technologies, so I like to teach open source tools where I can. Here are the open source technologies and tools that my students learned this semester:

Docs as Code

We started with a "gentle" introduction to technical writing tools by learning about the basics of source code control using GitHub. We also explore how to create technical documentation with Markdown, a lightweight markup system that's popular with developers. This combination of GitHub and Markdown is called "Docs as Code" because it uses the same tools for technical writers to manage documentation that developers use to manage source code.

Writing on the web

In this unit, students learn about how technical communicators can use HTML to create web content. We start with the basics of HTML before we explore advanced formatting with tags like <q> for inline quotes, <cite> for citations, <kbd> for keyboard input, <samp> for sample output, and so on. In doing so, students learn how to create accessible HTML so everyone can access their content.

This unit also has the students install an advanced code editor like Visual Studio Code so they can edit their HTML by hand. While Visual Studio Code is not open source, it does support all platforms including Linux.

Last semester, I also taught how to style contents with CSS, and had the students create a small professional profile website with a few pages. However, creating websites by hand proved to be distracting for my students, so I will probably remove the "website" portion of this unit the next time I teach the course. Anyway, it's rare for a technical writer (or anyone else) to create a website from scratch by editing HTML; instead, they would use a web content management system like Drupal or WordPress.

Desktop publishing

This unit transitions to using tools to do the formatting. We explore how to create professional-looking content that is ready for print or online viewing. For creating print-ready materials, we use Scribus. This is a very capable tool that I use professionally to create business cards, fliers, posters, and other print materials.

While other print-ready creation tools may be easier to use and more popular in industry, like Canva, using these other tools is actually less effective because then students only learn the templates and not the concepts. And by learning Scribus, students can transfer that knowledge of creating print-ready content to another tool, and become even more effective with software like Canva.

Students also learn how to use LibreOffice Writer to create professional book interiors. The key to working with a desktop word processor like LibreOffice is to use styles for everything and let the styles do the work for you. In this unit, students learn how to use paragraph styles, character styles, page styles, table styles, and other styles to create professional formatting like custom page sizes, left/right pages where chapters always start on a Right Page, page headers and footers, and format content including chapter titles, section headings, code samples, images, and other technical interior content.

XML as markup

To help students transition to our last big unit, we briefly explore how to use XML as a markup language. The rules to write XML are very similar to HTML, although the rules are more strict. To exercise XML as markup, students learn how to format a technical article using Simplified Docbook by hand using Visual Studio Code, and then Docbook using an XML editor.

Topic-based authoring. In this final unit of the course, students learn about a new way to create content by reusing and remixing content to create new kinds of output documents. This is called topic-based authoring, because you need to separate content into reusable "chunks" called topics. To do this, we leverage DITA, an XML-based markup system, using Oxygen XML Editor. While Oxygen is proprietary software, it runs everywhere, including Linux.

It's about the concepts

Throughout the semester, I focus on learning concepts. It's not really about learning a specific tool like LibreOffice or Markdown or Scribus—while they certainly demonstrate expertise those tools, they also learn skills that will transfer elsewhere: By learning how to use styles for everything and let the styles do the work in LibreOffice, students can also do the same in Word or another desktop word processor. After learning Markdown, students can quickly pick up AsciiDoc. Students can transfer what they learned about creating print-ready content in Scribus to creating print materials in Canva or other print tools.

And so on for the other tools; everything we learn can be easily transferred to learn a different writing technology or tool.

I'm always interested in improving this course and teaching the tools that industry professionals actually use. I'd love to hear from you: What's one thing you write all the time, and what app do you use to write it?

For example: If you're a technical writer, do you use DITA, and what app do you use? If you're a developer, do you write documentation in Markdown? If you're a manager, do you use Word to write status reports? If you're an editor, do you format book interiors using LibreOffice?

I'd love to hear from you! Email me at jim@hallmentum.com and let me know. Include as much detail as you're comfortable providing. A short paragraph about the app and another paragraph about the task would be great! I'll include your replies in a future "roundup" article—and more importantly, I'll share them with my students.

This article is adapted from Writing with open source tools by Jim Hall, and is republished with the author's permission.