Spence Green

التكرار يعلم الحمار

I work at Lilt. In addition to computers and languages, my interests include travel, running, and scuba diving. more...

Archive for the ‘Technical’ Category

Four More Points on Technical Writing

without comments

While working on our ACL2011 submission, I learned three more lessons about technical writing:

  • Use the section headings: Readers – and especially reviewers readings quickly – use section headings to navigate. While everyone knows to save space by removing lines containing only a few words that dangle from the end of a paragraph, few use the full line reserved for a section heading. This is a mistake. Make the section heading informative; use the space!
  • Add a data section: Don’t mix data with the model description. If the experiments use anything other than the PTB, reserve a special section for the data.
  • Use MATLAB for figures: I used to believe in PSTricks. But MATLAB is more robust, and writing a script to generate the figures can result in a massive time saving.
  • The narrative should not follow a chronology: I’ve written about this before, but it is so hard to apply at the end of a project when your mind is tuned to details. Readers with minimal background knowledge can be invaluable here.

Written by Spence

January 10th, 2011 at 10:52 am

Posted in Technical,Writing

Some Remarks on Technical Writing

without comments

For the past year I’ve been improving my writing. More specifically, I’ve been learning how to communicate technical information efficiently and with style. By “efficient” I mean that each word, paragraph, and sentence is contentful, and that thematic strings bind the story together in an accessible way. A reader can use the document as one might use an encyclopedia, i.e. there are elements throughout the running text that help the reader navigate. And by “style” I mean the cultivation of a voice: the arrangement of sentences; the careful use of symmetric; lexical choices. In technical writing, style decisions are made to help rather than to impress the reader.

“Style” in the popular sense should be avoided. In other words, don’t read Strunk and White. Geoffrey Pullum, co-author of The Cambridge Grammar of the English Language, wrote recently in the Chronicle of Higher Education,

The Elements of Style does not deserve the enormous esteem in which it is held by American college graduates. Its advice ranges from limp platitudes to inconsistent nonsense. Its enormous influence has not improved American students’ grasp of English grammar; it has significantly degraded it.

Read the rest of this entry »

Written by Spence

May 12th, 2010 at 2:43 pm

Posted in Technical,Writing