Technical Writer/Editor Portfolio

Welcome! This portfolio showcases selected examples of my technical and instructional writing drawn from my experience as an open-source contributor and an academic. The goal here is to demonstrate my ability to create clear, user-focused documentation and reference materials for diverse audiences.

Course Syllabus

The course syllabus is an informal contract between the instructor and the students. To be effective, it needs to explain the rationale for the course, present the specifics of how the course going to be conducted and graded, and explain the most important course policies. According to the Diátaxis framework, the syllabus is an example of a reference aimed at an audience of undergraduate students. The sample you’ll see demonstrates my ability to structure complex information, clarify expectations, and effectively communicate procedures.

Assignment Prompts

During my decade of teaching writing at the University of Washington, I composed a variety of assignment prompts to guide students. These prompts show my experience in writing step-by-step instructional materials, in many ways analogous to what Procida calls tutorials in his Diátaxis framework. The primary goal in both is the acquisition of skills. The audience here are first-year undergraduate students new to visual analysis and cultural criticism.

Here is a sequence of assignment prompts written in LaTeX from my Autumn 2013 class on advertisement:

Tutorial and Reference for “Eclectic Zettelkasten”

I have been developing the “Eclectic Zettelkasten” Emacs Lisp package since 2015 and have made it available on GitHub under GPL. While I have used the package extensively, public documentation is still in its early stages. The README you see below offers a brief tutorial for installing and customizing the package. It also includes some basic explanation of the structure of Zettelkasten created with it. The audience consists of Emacs users, though the boundary between developer and end-user is porous here, since it is quite difficult to merely use Emacs without doing at least some rudimentary customizations in Emacs Lisp. As such, the README demonstrates my ability to write concise instructions for the audience of peers.

The project’s README.md can be read directly on GitHub or locally:

Self-Documenting Code in Emacs Lisp

The following examples illustrate my approach to self-documenting code, a practice that supports both users and developers in understanding software functionality. This kind of documentation is best described in the Diátaxis framework as reference for the audience of Emacs user-developers.

The extensive docstring is part of the function definition. Only the beginning few lines of the actual definition is included for brevity. This particular function provides an interactive interface for the user to update symbolic links that were created to provide additional opportunities for wiki-linking between notes:

(defun ezeka--update-symbolic-link (linkname &optional kasten new-name)
  "Update the symbolic link LINKNAME, selecting a new target for it.
Unless KASTEN is specified, default to the same Kasten as the
original target; if not a string (or called with \\[universal-argument]), select
interactively. If NEW-NAME is a string, update the name of the link;
if not a string (or with \\[universal-argument] \\[universal-argument]),
ask for a new name interactively."
  (interactive
     (list (ezeka--grab-dwim-file-target 'grab-from-links 'interactive)
           (equal current-prefix-arg '(4))
           (equal current-prefix-arg '(16))))
  ...)

User-customizable variables — the two here are drawn from different parts of the package — also feature sizable documentation strings to explain their purpose and expected values:

(defcustom ezeka-find-file-functions
  '()
  "List of functions to call when finding Ezeka files.
Each function should accept two arguments: the file to find,
and optionally, the source from where the function was
called. TARGET should be a filename; SOURCE can be either a
filename or a symbol describing the source."
  :type 'list)

(defcustom ezeka-breadcrumbs-find-trail-function
  #'ezeka-breadcrumbs-find-linear-trail
  "Function called with TARGET and SOURCE to find the trail.
TARGET and SOURCE should be strings or symbols. Return
'primary or 'secondary if the trail was found (i.e. drop
breadcrumbs here), or nil if can't locate trail (i.e. don't
drop breadcrumbs)."
  :type 'function)

My choice of Emacs as the environment both for programming and for knowledge production has a lot to do with the importance that the Lisp family of languages — Emacs is written largely in Emacs Lisp — attaches to writing such self-documenting code. Every variable, function, or macro definition encourages inclusion of a short description of what it’s for, resulting in the closest thing to Donald Knuth’s ideal of “literate programming.” While it’s technically possible to “weave” (as Knuth called it) these docstrings into printable or browsable documentation, there is little added value, since this information is readily available through Emacs’s own interactive help system. The user does not need to actually ever need to read the implementation code to see these descriptions.

Conclusion

Thank you for reviewing my portfolio. Please contact me at richard<at>boyechko.net for any further information or additional samples.