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

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:

OH: it’s a readme, not an entertain me. @kimadeline_m #pycascades 😂😂😂

— Matthew Broberg is at @[email protected] (@mbbroberg) February 8, 2020

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:

Eleanor of Aquitaine
Hildegard of Bingen
Henry II of England
Frederick Barbarossa

— @besha.bsky.social (@besha) February 12, 2020

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. 

Miscellany

• From the realm of tech journalism (and in keeping with the theme of tech comm and critique), this piece from early career tech reporter Kylie Robison on How toxic tech culture failed the democratic process (again) which explores technochauvinism in last week’s Iowa caucuses.
• Twitter poll of interest: what to call “non-technical” or “soft” skills (a bucket in which technical communication skills are often–and without irony–grouped)
• CFP of interest: !!Con (May 9-10, 2020 in New York City)
• Sessions and opportunity grants announced for the 2020 Write the Docs conference (May 3-5, 2020 in Portland, OR)
• A writeup from my former Georgia Tech colleague Dr. Courtney Hoffman on how she incorporated elements of 18th-century science writing (and the periodic table) into her first-year composition course
• An explanation of whether to use “a” or “an” (with examples involving cake)

Worth 1000 words (recipe horror story edition)

WHAT HAS OCCURRED CANNOT BE UNDONE

I have trained a neural net on a crowdsourced set of vintage jello-centric recipes

I believe this to possibly be the worst recipe-generating algorithm in existence pic.twitter.com/cwQwOpUNDv

— Janelle Shane (@JanelleCShane) February 7, 2020

 

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.