The Challenges of Composing

Though I only officially spend two days a week in Circulation, I tend to be assigned anything that has to do with developing documentation on all of our policies and processes. This is probably because I once volunteered to re-write some portion of the Circ Manual and soon became the victim of my own success. Not that I really mind the writing assignments. Truth be told, they tend to be my favorite part of the job. Despite this affinity, it took me some time to realize that writing documentation for a department is vastly different from the sort of writing I specialized in previously. For example, think about both a piece on creating and checking patron records compared to an essay on Robert Browning and Florentine Portraiture of Women. The underlying purpose of both works is identical - the writer is attempting to convey some idea or concept to the reader in as clear and concise a manner as possible. However, when the execution of both works are examined, the differences are rather pronounced.

In my experience, documentation requires a tighter hand and a terser voice than an academic essay, at least more so than the essays I created. This is perhaps due to the lack of persuasion needed in documentation. In documentation it is not really necessary to get the reader to agree with an argument because it's not necessary to really argue anything. Documentation reflects an established consensus. In my work, documentation is composed and then approved in meetings, so everyone is on the same page. There are also procedural constraints - essentially, this is how we create patron records because of how the system works so it doesn't matter how much anyone hates having to remember to type all the zeros into an ID number.

Because rhetoric isn't necessary in documentation, the piece is more to the point. This tendency to concision an unbelievable challenge for me as I have always been a wordy writer, as this sentence amply demonstrates. Put simply, I babble. I brazenly defy Strunk and White's call to "Omit needless words", relishing melodic though not necessarily pertinent turns of phrase. Even worse, a brief survey of essay titles from my first two degrees demonstrates a shocking affection for alliterative titles. When writing academic essays on history or novels - where story is paramount - this wordiness can be easily integrated and can even be a boon. But when the purpose of a piece is to help a new and harassed Circ Supervisor figure out how to create an alumni record on a weekend when the alumni office is closed and when the impatient patron at the desk, who forgot their alumni card, really wants to leave with their books, this predilection will only earn the author their co-worker's ire.

So what does a useful piece of documentation look like? This will certainly vary between different organizations and their particular information needs and styles. Below is what I do to make documentation better for me and my coworkers.

1) Keep it Visually Simple: By this I mean no dense blocks of text. Think of the difference between a reference book and a monograph.* A piece of documentation should be easy to browse. The reader should be able to pick out the portion of the process or information they need. Formatting is key here - setting out important details in bold or providing numbers for long sequences of steps. I often begin an entry for the Circ Manual with a short preamble that details the purpose of the documentation and/or the process or policy it describes. For longer processes, such as consortia borrowing, I might also include a paragraph that is a general overview of the entire process. From there I'll get into the step by step way to carry out the desired task. I make sure that the steps are numbered and well spaced so that the reader can follow along easily on the screen or via a printout.

2) Know Your Audience: Departmental documentation is used by both full-time and student supervisors. This means that as I writer I need to consider the reader's learning style, job responsibilities, and comfort level with technology.

In terms of job responsibilities, I mean what sort of procedures the reader can be expected to carry out. For example, a full-time Supervisor can and should be comfortable looking up the status of an alumni in Banner before creating a record. However, Student Supervisors do not have Banner access and cannot verify patrons this way. If the documentation leaves the reader lost or at a dead-end, it's ineffective and needs to be changed. The documentation should provide work-arounds or alternatives. For example, is this a dinner break and can they ask the patron to wait or is it during normal business hours and is there someone else on campus they can contact?

In addressing comfort levels with technology, I tend to err on the side of overly explaining. While it's not the point of "Place your dominant hand on the mouse and move it laterally to the Start button...", I do try to break a process down thoroughly. Those who are more experienced can easily skim and pull out the basics and those who need the full click-by-click can follow along. If writing documentation on a process that involved technology of any sort, I like to provide screen-caps. I've never thought of myself as a very visual person, but I have found that seeing that my screen matches the documentation can be comforting and can help when things get a little complicated. By this I mean I can sometimes condense steps by saying "Make sure your screen matches that below" instead of trying to verbally describe how a menu should be formatted. But I also try not to go overboard. My rule is that if there's a significant change in the menu or something else pops up, you make a new screen-cap. Otherwise, a short sentence will suffice.

Variations in learning styles can be difficult to address. But learning styles I mean realizing that people learn differently and thus expect different things from their learning materials. I don't think it's necessary to follow something like 4mat slavishly to ensure that your two page summary on shelving is absolutely inclusive (though I recommend giving it a read to get a better sense of the cognitive differences out there in your readers). Instead, keep a critical eye on your work and ask if the readers will find your work easy to understand. Is your vocabulary and terminology at the right pitch? Are you including enough visual cues (or too many)? Are you giving enough examples to help reader's apply the procedure? Additionally, I've found that giving a rationale for a process will often mean that it will stick with people more. By explaining that all of the zeros in a patron's ID number are necessary to allow uploads from Banner to overlay properly and prevent duplicate records, that bit of information might stay more firmly lodged in one's brain (and make record clean up all the more easier for me).

3)Date Your Footer or Indicate Edits: This is a pet peeve of my boss and one that I've come to take on myself. In order to make sure that the most recent, and thus most accurate, version of a piece is being used, note the footer with a "Last Updated" section. Do NOT use the auto dating function in Word. That will change the footer every time you open the document. Make it a habit when editing to change the footer and add initials if necessary. If using a wiki, this is an unnecessary step (which is one of the reason's why I'm longing to move our documentation to one!). If your department is a fan of track-change in Word feel free to use that (I am not and since I am often the only person editing the documents, it's not really necessary).


This is all I can think of for now, but I hope to add to this in the future!



*Bates, Marcia J. "What Is a Reference Book: A Theoretical and Empirical Analysis." RQ 26 (Fall 1986): 37-57. I have read this article at least twice in my program already and it's still pertient.