Open source technologies we’re excited about

Using open source tools and open technologies makes it possible for anyone to practice technical writing.

February 14, 2024

I teach several courses on technical writing and I like to use open source software and technologies in my class. This semester, I taught a course on writing with digital technologies where we learned about various tools and technologies that technical writers use in the industry, including HTML, CSS, DITA, LibreOffice, and other apps.

I asked my students about what open source writing tools they were most interested to learn about, including what open technologies they were most likely to use in their careers. We identified this list of the most exciting open source tools and technologies for technical writing:

HTML and CSS

We started by learning HTML, the Hyper Text Markup Language. While many technical writers will use a web content management system to create web content, technical writers still need to understand how HTML works at a basic level. HTML is the foundation of every website, and provides a solid starting point to learn other digital writing technologies including XML and DITA.

Authors can leverage the flexibility of HTML to create all kinds of technical documentation, especially websites. Technical writers can also combine HTML with CSS stylesheets to make all their content consistent and easy to read. For example, we learned how to write how-to articles and other web content, including adapting our websites to mobile displays using Response Web Design in our CSS.

screenshot of editing HTML — image: Jax Davidson

<!DOCTYPE html> 
<html> 
<body> 
	<h1> This is an Example heading</h1> 
	<p> Example paragraph </p> 
</body>
</html>

code sample: Abigail Karger

For more information, Mozilla’s MDN Docs has an excellent Introduction to HTML tutorial and reference guide that helps you learn how to write your own web pages in HTML.

Markdown

Markdown provides an easy way to format documents using a lightweight markup system. Markdown tries to look like a plain text document, making it intuitive to use. Formatting markers emulate what we might use to emphasize in a plain text file, such as ** for bold, * for italics, and underlining headings with === or –--.

This is the title of a standard markdown document
=================================================
If I wanted to add a subheading, I would simply do this.
--------------------------------------------------------
Now, if I want to add italics, I would add an *asterisk* to the beginning and end of my word. 
Bold is essentially the same thing, except this time there are **two** asterisks instead of one.
Writing inline code can be done by adding one `backtick` at the beginning and end of my code. 
But if I need to write in block code, I would do so like this:
```
This is a sample piece of block code writing
It uses back ticks the same way as inline code, except three of them at the top and bottom of my writing
This is not an apostrophe, this is a key called a "backtick" 
The backtick key can be found to the left of your "1" key on a standard QWERTY keyboard
```

code sample: Alex Molina

Markdown is a common writing technology in open source platforms like GitHub, which enables collaborative documentation between multiple contributors. GitHub and other platforms can transform the Markdown source directly into HTML, or you can use a command line tool to do the same:

screenshot of Markdown output — image: Alex Molina

To learn more about how to write documentation using Markdown, refer to the Markdown Guide. This is a free and open source guide to writing with Markdown.

DITA

DITA is a writing technology that was designed to solve the copy/paste problem. For authors who need to remix and reuse content between projects, DITA can be a powertool in their digital writing toolkit. While you can use a tool to edit DITA topics, DITA files are plain text that use XML as markup, so you can use any kind of editor to manage DITA files and projects.

Using DITA, technical writers can employ several key topic files, such as Concepts to describe a thing or a process, Tasks to define the steps of a process, and References to provide just the facts such as system requirements. Authors can connect these topics together using a DITA Map file and transform them into a variety of output formats including PDF, EPUB, and websites. Advanced DITA authors can also use DITAVal files to create conditional text for different audiences, or based on product and platform.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="default_ver">
    <title>Default Version</title>
    <shortdesc>The Default Version of the software.</shortdesc>
    <conbody>
        <p>Let's say we have a software package that comes in various versions or "flavors," where
            each "flavor" is basically the same as the other versions, but packaged in a different
            way. This file describes the <keyword>Default</keyword> version without any
            modifications.</p>
    </conbody>
</concept>

code sample: Jim Hall

screenshot of DITA output — image: Jim Hall

To explore DITA on your own, download the DITA Open Toolkit, an open source DITA transformer. Write your DITA files with any text editor and use DITA OT to create PDF, HTML, and other kinds of output.

LibreOffice

Quite a lot of technical writing in the industry is still performed in a traditional desktop word processor. LibreOffice provides an excellent and mature word processor in LibreOffice Writer. My students found LibreOffice very easy to learn and use to create professional-looking documents.

The key to using LibreOffice Writer effectively is to use styles everywhere. LibreOffice provides styles for paragraphs, characters, pages, frames, and other styles. We used these styles to create different kinds of documents in a variety of layouts including US Letter and Crown Quarto formats. Styles allows writers to streamline the writing process by customizing the styles to make documents look exactly the way you want. For example if you update the Heading 1 style, LibreOffice will change every top-level heading to look the same.

screenshot of LibreOffice Writer — image: Matt Bong

LibreOffice is available on all platforms, including Linux, Mac, and Windows. Find it at the LibreOffice website.

Using open source tools and open technologies makes it possible for anyone to practice technical writing. Whether you are doing it for a hobby, transitioning to a new career, or writing for a work project, these tools and technologies provide a solid foundation to explore technical communication.

This article was co-authored by Jim Hall, Jax Davidson, Alex Molina, Matt Bong, Mollie Barnes, Natalie Jacobson, and Abigail Karger.

Jim Hall is an open source software advocate and technical writer. At work, Jim is CEO of Hallmentum, an IT executive consulting company that provides hands-on IT Leadership training, workshops, and coaching.

Jax Davidson

Alex Molina

Matt Bong

Mollie Barnes

Natalie Jacobson

Abigail Karger