A checklist for writers

Technology both shapes and reflects our values. What do we value in scholarly writing, and how well do our technological choices match those values?

I look for software that supports four necessary or possible qualities of good scholarly writing:

1. expository writing should be explicit and unambiguous
2. the writing process is iterative: good writing only comes from rewriting
3. academic writing in the natural sciences is often collaborative; this is becoming less rare in the humanities (although not necessarily in the cargo-cult humanities )
4. born-digital writing should be reusable

In a digital enviroment, to write explicitly and unambiguously means more than choosing our words well: it also means expressing the structure and contents of our writing explicitly and unambiguously. Our writing should embody the fundamental principle of separating concerns in our digital work: our first goal is to express our ideas clearly, not to exercise our typesetting skills, so we need a format that that can explicitly and unambiguously express structure. We might choose an XML-based semantic markup system, or some semantically classed “markdown” system such as markdown or textile. What we should not choose is a “word processor.” Even if you can approximate a semantic structure using a carefully chosen set of “styles” (a tell-tale term!), you will be planting your semantic hints in a thick forest of code focused on the particulars of displaying your text visually. Note that it’s perfectly possible to express this irrelevant information using XML formats like OpenDocument. Our question is not “is this an XML format?” but “does this format express the semantics of my document?”

In considering how to support the remaining items in our list, we should look for examples beyond the humanities, since expository prose is not the only form of writing that shares these qualities. In particular, each is characteristic of good composition in computer programming, and computer programmers routinely use software that directly takes account of each of these qualities.

Programmers use version control systems to work with the entire history of a document to update, restore or compare versions. Version control systems also simplify collaboration, and allow mulitiple contributors to work simultaneously on a document. Changes can be silently integrated and shared; if two authors simultaneously make conflicting changes, version control systems can recognize that, and offer authors options to reconcile conflicts manually. There are many good, freely available version control systems. One reason that humanists are less familiar with them than they should be is that version control systems work best with textual data: the binary formats that word processors produce are a major obstacle to integrating our writing in version control, but once we have adopted a text-based semantic format, that obstacle vanishes, and we have a writer’s desktop that lets us write iteratively and collaboratively.

Programmers also provide a model for reusing our writing. Units of code are often packaged in libraries that other programs use. Programmers working on large projects manage the potentially complex interrelations and dependencies of of different libraries and programs using build systems. We are not yet accustomed to thinking about automating the reuse of our writing, but there is no technical obstacle to doing so. We could use build systems to assemble chapters into a book, incorporate common navigational headers into all the pages on a web site, or automatically update an index if one section of a text changes, to name just a few obvious examples.

So our checklist of required tools for writers includes:

• an editor that works comfortably with semantically structured text
• a version control system
• a build system

I plan to add a series of posts with the tag writing to look at how we can work with tools like these to write more effectively in a digital setting. Meanwhile, take the checklist to your college or university IT department, and ask what specific software they support for semantic editors, version control systems and build systems. I would love to learn of an academic institution that is not just pressing commercial word processing software on its students and faculty, but I don’t know of one.