Sometimes Dragons

Docs Roundup 1.2

Share via Twitter Share via Facebook Share via Linkedin Share via Reddit

Recent docs (and tech comm) items of interest: README files; code comments; medieval tech comm; tech comm and critique; a miscellaneous usage issue illustrated with cake

Illustration of 15th-century Burgundian scribe Jean Miélot writing at his desk. He is surrounded by a variety of manuscripts and writing implements.

README files

For many of us (especially those of us who installed software sometime in the previous century) README files are a familiar form of technical documentation that we encounter as consumers. For those unfamiliar with the role README files play today (especially in public-facing software projects), GitHub has a nice definition of README files in its help docs:

A README file, along with a repository license, contribution guidelines, and a code of conduct, helps you communicate expectations for and manage contributions to your project.


A README is often the first item a visitor will see when visiting your repository.

Looking for resources on creating README files? Check out this README template from Billie Thompson. You can find more templates and guidance at Make a README (many thanks to Lisa Wold Eriksen for surfacing this resource). Or Nerando A. Johnson’s writeup on Writing The Needed ReadMe has a great take on why developers should care about this type of documentation (as well as how to get started writing one):

So here you are, you have good written code and uploaded it to whatever open source repository you use Github, Gitlab, Bitbucket or even your own hosted repository. You are sure your code works, you have tested it, retested… even tested it on Becky’s machine and refactored it on your machine and sure it works. So the question to the person who looks at you[r] repo is …… HOW THE HELL DOES IT WORK ????? 

Finally, a nice reminder from Matt Broberg about the purpose of these types of files:

Code comments

To comment or not to comment, that is the question (and one that seems to pop up quite regularly). Case in point: Sarah Drasner wrote up this excellent piece on The Art of Comments in response to a 2017 thread debating the value of code comments. She was kind enough to surface it again this week in a more recent discussion on the topic. Notably, while Drasner is for commenting code, her take on the matter nicely acknowledges how complex (and non-standardized) the practice is:

I believe commenting code is important. Most of all, I believe commenting is misunderstood. I tweeted out the other day that “I hear conflicting opinions on whether or not you should write comments. But I get thank you’s from junior devs for writing them so I’ll continue.” The responses I received were varied, but what caught my eye was that for every person agreeing that commenting was necessary, they all had different reasons for believing this.


Commenting is a more nuanced thing than we give it credit for. There is no nomenclature for commenting (not that there should be) but lumping all comments together is an oversimplification.

Indeed, the purpose and audience for code comments can vary greatly (and, as my colleague Rachel Stephens reminded me, a developer’s future self is often the unintended beneficiary of such comments, especially when attempting to decipher code written as a very junior dev). For a take on code comments from a tech writer’s perspective, check out this post from Tom Johnson on Tips for writing code comments in developer documentation.

Medieval tech comm

Earlier this week, Laurie Voss put a call out for biographies for his TBR list. I was delighted (although not surprised) to see numerous respondents suggest Hildegard of Bingen:

Fun fact: although Hildegard is more widely known for her contributions to music and theology, she is also considered a medieval technical communicator. As per Susan Rauch’s  article “The Accreditation of Hildegard Von Bingen as Medieval Female Technical Writer”:

Primarily known as a mystic and writer of poetry and music, Hildegard’s technological and medical texts have slowly gained interest within the medical community. Her texts Physica and Causae Curae, written in the style of modern-day patient history and physicals, outline patient symptoms, causes and effects, preceded by a treatment plan. This article examines Hildegard von Bingen’s medical works, identifying her as a scientific or medical technical writer within the same context from which scholars assign Chaucer the same title, and from which all medical and scientific writers of medical texts can be professionally accredited as technical communicator or writer.

The argument for Chaucer as Technical Writer has been made via his Treatise on the Astrolabe (a tool used by astronomers and navigators). Rauch’s article is in good company among other efforts to surface premodern technical communication efforts beyond Chaucer. It is also a reminder that not all technical communication is about software (and that documentation has been around for a really, really long time).

Tech comm and critique

In my 1.1 Docs Roundup I highlighted a recent collection of essays that approach technical communication from various perspectives grounded in critical theory. In a similar vein, Stephanie Morillo (whose book I reviewed earlier this week) recently published a piece in her newsletter on Examining code through the humanities in which she describes her introduction to the field of Critical Code Studies:

This past fall (fresh out of grad school and nurturing a kick to read academic literature that I had no time to read in my Master’s program) I found an essay by Mark C. Marino on something called Critical Code Studies (CCS). It’s an interdisciplinary field that examines computer science through the lens of the social sciences. For years, I’ve thought about questions like: “Why do we employ master/slave terminology in software?” and “Why are most programming languages used in an enterprise setting based on English?” I’ve always bristled against the notion that computer science—and programming specifically—were “logical”, “rational”, “neutral”; that they somehow existed outside of the ontological framework known as real life, which is “irrational”, “emotional”, “messy”, “subjective”. 

We may like to think of engineering as a highly rational and objective discipline. Yet, as demonstrated by Morillo’s examples, the decisions we make in naming conventions, writing code, and writing about technology are not made in a vacuum: yet another reason for tech comm practitioners to be aware of forms of critique that are happening in adjacent academic or theoretical fields. 


Worth 1000 words (recipe horror story edition)


Have a recent/upcoming docs item you want me to know about? Drop me a line or find me on Twitter.

Disclosure: GitHub is a RedMonk client.

Image information: Wikimedia Commons; image is in the public domain.

No Comments

Leave a Reply

Your email address will not be published. Required fields are marked *