Archive for the ‘language’ Category

« Older Entries

Shakespeare and Document Control

Friday, April 20th, 2012

I’ve never thought of Shakespeare in the context of technical writing, but in this article Josh Stubbs makes the connection. It’s a great article and definitely worth reading – you’ll probably learn something about Shakespeare you didn’t know and it’ll help you with your documents as well.

There is no doubt that William Shakespeare was an extraordinarily gifted writer but his document control left room for improvement.

This article will show several document control mistakes that Shakespeare made and describe why the issue is still relevant to technical writers 400 years later

#1 KING LEAR – Not Uniquely Identifying Each Document and its Release

Shakespeare produced two different versions of King Lear. Between these two versions there are nearly 300 different lines of dialogue that significantly affect the over all tone of the play.

Scholars have debated which was the Bard’s preferred version. Was one the fully realized tragedy exploring the themes and ideas to their conclusion or was the other a more direct and visceral plot meant to capture the attention of wandering groundlings?

WHY IT IS RELEVANT

Readers will make their own assumptions about the various drafts of your document and use their own method to determine several documents with similar names. A reader will naturally assume that a document is complete if it is labelled “Final Draft” or “Final Draft (2)” and they do not know that there is FINAL Final Draft or a Final Draft (3).

Posted in language, technical communication | No Comments »

Merriam-Webster Dictionary of English Usage on Google Books

Monday, April 2nd, 2012

The Merriam-Webster Dictionary of English Usage is one of my favourite language reference books. It has a place on honour on my computer desk bookshelf right beside  the Gage Canadian Dictionary and The Oxford Guide to Canadian English Usage. Sadly, it’s out of print although copies aren’t hard to track down. More sadly, there’s no e-book edition – I would love to have this on my Kindle.

However, it is now in Google Books as a scanned book, apparently with the editor’s permission.

The reason it’s one of my favourite books on language is that it’s eminently readable. The entries vary from a few paragraphs to more than a page, covering about 2,300 words. Not a lot in the context of the whole English language, but the choices are well though out, covering many words that are commonly misused. For a good example, look at the entry for “hopefully” on page 512.

The book is searchable, fortunately, because there’s no linked table of contents so you can’t jump to a specific word unless you search the book. (Anyone who wants to create a page that links to each entry in the book will have my undying gratitude). However, that might destroy the fun of browsing through this wonderful work.

Posted in books, language | No Comments »

The Beauty of Typography

Monday, March 26th, 2012

When we think of typography, we (at least we English speakers) tend to think of a really small set of letters, numbers, and symbols. After all, most textual information can be expressed in the 127 low order ASCII character set. But it’s quite different if you’re a speaker or reader of a non-Roman language – Japanese or Arabic, for example.

In Smashing Magazine,  The Beauty Of Typography: Writing Systems And Calligraphy Of The World looks at the typography and calligraphy of many of the world’s non-Roman languages. It’s a fascinating article and beautifully illustrated.

The beauty of typography has no borders. While most of us work with the familiar Latin alphabet, international projects usually require quite extensive knowledge about less familiar writing systems from around the world. The aesthetics and structure of such designs can be strongly related to the shape and legibility of the letterforms, so learning about international writing systems will certainly help you create more attractive and engaging Web designs.

Pick any language you like: Arabic, Chinese, Japanese, maybe Nepali? Each is based on a different writing system, which makes it interesting to figure out how they work. Today, we’ll cover five categories of writing systems. This may sound tedious and academic, but it’s not. If you take the time to understand them, you’ll find that they all give us something special. We’ve tried to present at least one special feature of each language from which you can draw inspiration and apply to your own typography work. We’ll cover: East Asian writing systems,Arabic and Indic scripts (Brahmic). If you are interested, we will cover Cyrillic, Hebrew and other writing systems in the next post.

Posted in language | No Comments »

Medieval annotations

Monday, March 26th, 2012

It seems that medieval monks were human too, if the annotations found in the margins of illuminated manuscripts are any indication. I mean: “Now I’ve written the whole thing: for Christ’s sake give me a drink” isn’t very holy, but it is very human.  Living in the Margins discusses the The Means of Communication issue of Lapham’s Quarterly, which contains a collection of complains and marginal notes written by the copyist monks. It seems the monks were a sharp tongued and saucy bunch.

These lovely and lively interjections represent just a small range of expression that one finds throughout medieval manuscripts. And as Michael Camille documents in Images on the Edge: The Margins of Medieval Art, it is in these marginal comments that we learn as much—if not more—about the medieval world as we do from the texts themselves. Marginalia might include comments like the ones from our miserable monks, but also an entire free-flowing range of artistic flourishes and doodles that make up the edges of medieval manuscripts. “Once the manuscript page becomes a matrix of visual signs and is no longer one of flowing linear speech,” Camille writes, “the stage is set not only for supplementation and annotation but also for disagreement and juxtaposition—what the scholastics called disputatio.”

Posted in books, language | No Comments »

New article on TechWhirl

Thursday, March 22nd, 2012

I have a new article up on the TechWhirl site: Technical Writer Tips and Tricks: PDF and Online Help Documentation Translation. It turned out to be one of the easier articles I’ve written, as it’s based on notes that I give to translators for documentation at the TSX. Thanks to Conniie Giordano for polishing it to a fine shine.

Over the past few years, I’ve had to manage the translation into French of user guides and online help for TSX SecureFile. The documentation consists of PDF user’s and administrator’s guides produced using unstructured Adobe FrameMaker and web-based online help produced using Quadralay’s WebWorks ePublisher.

This article is based on a relatively simple scenario – a lone technical writer with a small number of manuals being translated into one language. I’m not going to discuss how to find a translator as that may be out of your control; your company may already have a translation service in place. But the tools the translation service has available are important to your success.

Posted in language, technical communication | No Comments »

Resizing content for the small screen

Wednesday, February 29th, 2012

Technical writers who produce both print documentation and online help know that you can’t just pour content from one format to another – the different media require different organizational techniques and writing styles. Now that we’re producing documentation for portable devices with small screens, we have to work even harder to make sure the content fits the device. Adobe’s Tech Comm Suite Evanagelist Blog has just published an excellent article by Maxwell Hoffman that explores this subject in more detail. It should be required reading for any writers who are producing online content.

When we read text on a handheld device, if the text is bulleted, indented, or formatted like a typical “technical” document, we can see the equivalent of about two or three spoken sentences. As soon as we “thumb down” to the next page, most of the visual context vanishes. We can only remember so much. This may be the reason that advertisement screenshots for eReaders universally display paragraphs from novels, not indented, bulleted text from technical communications.

Although a great deal of content from blogs and social media is pithy enough for handhelds, oceans of technical instructions destined for your smartphone screen are nowhere near ready to fit the confines of the small screen. If you are presenting steps or key points in a numbered or bulleted list, at a minimum, each item should be less than an iPhone screenful. If that bulleted “thought” or point straddles three or four Smartphone screens, reader retention will dramatically shrink.

I had an epiphany about this point recently when I found an online white paper I had authored about 5 years ago. My thumb nearly fell off scrolling through just three bulleted items. The content was effectively written and formatted for a “full” screen, but I didn’t have the patience for my own thoughts presented in the confines of a handheld smartphone.

Posted in language, technical communication, usability | No Comments »

« Older Entries