{"id":10839,"date":"2025-06-02T03:00:00","date_gmt":"2025-06-02T07:00:00","guid":{"rendered":"https:\/\/www.both.org\/?p=10839"},"modified":"2026-02-04T15:00:22","modified_gmt":"2026-02-04T20:00:22","slug":"writing-with-open-source-tools","status":"publish","type":"post","link":"https:\/\/www.both.org\/?p=10839","title":{"rendered":"Writing with open source tools"},"content":{"rendered":"
\r\n
\r\n \r\n <\/i>\r\n <\/a>\r\n <\/span>\r\n<\/div><\/div>\n

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<\/em> 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.<\/p>\n\n\n\n

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:<\/p>\n\n\n\n

Docs as Code<\/strong>. We started with a \u201cgentle\u201d introduction to technical writing tools by learning about the basics of source code control using GitHub<\/a>. We also explore how to create technical documentation with Markdown<\/a>, a lightweight markup system that\u2019s popular with developers. This combination of GitHub and Markdown is called \u201cDocs as Code\u201d because it uses the same tools for technical writers to manage documentation that developers use to manage source code.<\/p>\n\n\n\n

Writing on the web<\/strong>. In this unit, students learn about how technical communicators can use HTML to create web content. We start with the basics of HTML<\/a> before we explore advanced formatting with tags like <q><\/code> for inline quotes, <cite><\/code> for citations, <kbd><\/code> for keyboard input, <samp><\/code> for sample output, and so on. In doing so, students learn how to create accessible HTML<\/a> so everyone can access their content. This unit also has the students install an advanced code editor like Visual Studio Code<\/a> so they can edit their HTML by hand. While Visual Studio Code is not open source, it does support all platforms including Linux.<\/p>\n\n\n\n

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<\/em> proved to be distracting for my students, so I will probably remove the \u201cwebsite\u201d portion of this unit the next time I teach the course. Anyway, it\u2019s 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<\/a> or WordPress<\/a>.<\/p>\n\n\n\n

Desktop publishing<\/strong>. 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<\/a>. 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<\/a>, using these other tools is actually less effective because then students only learn the templates<\/em> and not the concepts<\/em>. And by learning Scribus, students can transfer that knowledge of creating print-ready content to another tool, and become even more effective<\/em> with software like Canva.<\/p>\n\n\n\n

Students also learn how to use LibreOffice Writer<\/a> to create professional book interiors. The key to working with a desktop word processor like LibreOffice is to use styles for everything<\/em> and let the styles do the work for you<\/em>. 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.<\/p>\n\n\n\n

XML as markup<\/strong>. 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<\/a> by hand using Visual Studio Code, and then Docbook<\/a> using an XML editor.<\/p>\n\n\n\n

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

Throughout the semester, I focus on learning concepts. It\u2019s not really about learning a specific tool like LibreOffice or Markdown or Scribus\u2014while 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<\/a>. 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.<\/em><\/p>\n\n\n\n

\n\n\n\n

I\u2019m always interested in improving this course and teaching the tools that industry professionals actually use. I\u2019d love to hear from you: What\u2019s one thing you write all the time, and what app you use to write it?<\/p>\n\n\n\n

For example: If you\u2019re a technical writer, do you use DITA, and what app do you use? If you\u2019re a developer, do you write documentation in Markdown? If you\u2019re a manager, do you use Word to write status reports? If you\u2019re an editor, do you format book interiors using LibreOffice?<\/p>\n\n\n\n

I\u2019d love to hear from you! Reply below and include as much detail as you\u2019re comfortable providing. A short paragraph about the app and another paragraph about the task would be great! I\u2019ll include your replies in a future \u201croundup\u201d article\u2014and more importantly, I\u2019ll share them with my students.<\/p>\n","protected":false},"excerpt":{"rendered":"

Aside from my other work, I also teach a few university courses about technical writing. One class I<\/p>\n","protected":false},"author":33,"featured_media":3887,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_lmt_disableupdate":"","_lmt_disable":"","footnotes":""},"categories":[135,158,178,579],"tags":[780],"class_list":["post-10839","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-education","category-open-source","category-tools","category-writing","tag-writing-tools"],"modified_by":"David Both","_links":{"self":[{"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/posts\/10839","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/users\/33"}],"replies":[{"embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=10839"}],"version-history":[{"count":1,"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/posts\/10839\/revisions"}],"predecessor-version":[{"id":10840,"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/posts\/10839\/revisions\/10840"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/media\/3887"}],"wp:attachment":[{"href":"https:\/\/www.both.org\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=10839"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=10839"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=10839"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}