Docs-as-Code Tooling: A Comparison

Artist visualization of Johannes Gutenberg in his workshop, showing his first proof sheet.

With the range of software documentation tools available it’s difficult to know where to start.

I recently compared available documentation tools to determine which are best suited for a project I’ve been working on. What follows is a summary drawing from my own practical experience working as a technical writer while considering perspectives of others working in the field.

Continue reading...

Is Canada making a Faustian bargain with corporate AI?

Faust Selling His Soul To Mephistopheles, Jan Jansz. Van Buesem (Dutch, 1599 – 1649)

What follows are some reflections in light of news about AI regulation. The thesis is that, while modern AI emerged largely from Canadian-funded research, broader economic benefits to working people are difficult to see on the horizon.

Throughout 2023, a common theme in political commentary in Canada was whether the country is ‘broken.’ While the national mood has been better, a sense of defeat is perhaps a feature of the Canadian identity.

Continue reading...

William Morris and the digital age

Morris image from grapheine.com

Our current tech age is, in some ways, analogous to what previous generations faced with industrialization. Like the Industrial Revolution, narratives of progress through technology are met with labor upheavals, inequality, and alienation.

In the 19th Century, William Morris responded to the “dark Satanic Mills” of industrialization by calling for social reform and upholding the medieval idea of craft. To counter tech disenchantment in our own time, we can consider whether Morris’s legacy can inspire today’s digital economy.

Continue reading...

What if Simone Weil worked in tech?

Imae from book cover The Need for Roots at penguinrandomhouse.com/

Tech companies have marketed a progressive image of their organizations and brands. Recent events, such as mass layoffs and reports of toxic work cultures, have brought long-overdue discussions and critiques of this sector into the mainstream.

We can hope that this pushback will lead to positive changes. However, it is difficult to find the language to describe what the modern tech industry even is. Terms like “technofeudalism” help explain the big-picture role of tech monopolies in the global economy. Still, there is also a need to understand and express the day-to-day experiences of workers.

As a tech worker, I’ve often asked myself, “What if Simone Weil worked in tech?”

Continue reading...

The aesthetics of technical documentation

aesthetics of documentation

My recent presentation at Université Paris Cité International Conference on Technical Communication discussed technical documentation as an aesthetic.

Aesthetics is most often associated with cultural phenomena such as art, music, fashion, and film. However, we can consider the term more broadly.

Technical writers and communicators are creating artefacts that reflect sophisticated products and technologies. These artefacts are often the result of collective efforts of many talented people. A challenge is designing documentation that reflects this sophistication while keeping it accessible for end users.

Continue reading...

Automating docs-as-code to Google Docs conversion

bash script for pandoc conversion

A challenge of maintaining docs-as-code is organizing comments and feedback.

It is inconvenient for team members to download a repo and comment directly in the markdown. Tools for commenting directly in the browser can be hit-and-miss. Besides, team members will appreciate using familiar tools rather than introducing new ones.

A solution is Pandoc to convert markdown to Google docs. This article will show simple shell scripts to bulk convert markdown files for Google Drive.

Continue reading...

Corpus based methods for nonverbal communication

Image source: book Silent Language

The following was prepared for: Research methods in Linguistics: Multidisciplinary approaches. University of Madeira, Portugal

In the Lebenswelt of everyday communication, it is the combination of fluid verbal and nonverbal semiosis that creates meaning. While many insights can be gained from textual discourse analysis, the nuances and richness of human communication comes to the fore when it is an integrated whole that includes nonverbals. If phenomenological experience doesn’t lead one to this conclusion, it is also supported by quantitative studies suggesting two-thirds of human communication is nonverbal (Burgoon et al., 2016).

Continue reading...

Natural resources and communication: when the rhetorical tradition confronts the real economy

image from Smithsonian Institution

The following is a draft chapter for a forthcoming book.

The backdrop to a discussion of natural resources will be familiar to many readers in a business or policy audience. The global economy is fuelled by increasing amounts of finite resources. Trillions of dollars will need to be invested in the coming years to simply meet UN Development Goals (UNCTAD, 2014). The amount of minerals, ores, fossil fuels, and biomass consumed globally is projected to triple by 2050 (National Intelligence Council, 2013).

Added to this are fiscal stimulus packages, climate targets, and associated green technology mandates projected to drive demand for strategic minerals (Jones, Elliott, & Nguyen-Tien, 2020). At the time of writing (October 2021), food and energy inflation are at levels not seen in decades and supply chain disruptions are a reminder of the interconnectedness of the global material metabolism.

Continue reading...

Chemistry drawing with Fabric.js

chemistry drawing with fabric.js

This project addresses the need for a simple, lightweight chemistry drawing tool for e-learning.

While proprietary drawing tools like ChemDraw offer impressive features suitable for the professional chemist, they are often overkill for online learning applications. Integration with e-learning platforms can be both complex and costly.

In collaboration with chemistry instructors, the answer was a Javascript based web application for drawing chemical structures.

Built using Fabric.js the basic functionality includes:

Continue reading...

Mapping the contours of human languages

Map of languguages in US - ESRI

Published on GoGeomatics.

The geospatially-inclined might not typically think of linguistics as within their purview. However, approaching human language from a geographical perspective can be both practical and fascinating.

The term geolinguistics refers to the use of maps in linguistic research. This might include the distribution, diversity, evolution, and dynamics of languages. Although the field has been of interest primarily to linguistic researchers, it opens up opportunities for the broader geospatial community to engage in original, interdisciplinary work.

Continue reading...