Using a Controlled Vocabulary

Val Swisher, founder and CEO of Content Rules and expert in "global ready" content creation, blogged recently about using short sentences in technical communication. According to Val, writing short sentences is the single-most important factor in creating content that is easy to read and translate.

While I absolutely agree with Val that using short sentences is important to create clear content--whether or not it will be translated, that's only one stepping stone on a path to creating clear, usable, and reusable content. At least equally important are the words in those sentences.

We're all aware that it is important to choose our words so that they accurately convey the intended meaning. Anyone with more than a cursory understanding of technical communication also understands that those words must be appropriate for the audience. Further, most technical communicators are aware that specialized audiences use and understand certain domain-specific vocabularies. However, it is possible to do a great job of choosing wording that conveys meaning, suits the audience, and uses the audience's specialized technical "language" to write effective text that is not particularly efficient.

Efficient Writing

There are many ways to increase efficiency in the writing process, such as writing structured, topic-based articles for reuse, using a content management system, and writing to standards. Perhaps the most important factor for efficiency in the writing product for global content is to use a controlled vocabulary.

Controlled vocabulary is not a new concept. Biologists, librarians, and programmers have long used limited vocabularies to refer to particular items, concepts, or structures in order to make them understandable across broad audiences. The classification system used for biological taxonomy is an example of a controlled vocabulary. There are many ways by which a dog may be described. The taxonomic system provides a common structure and a common vocabulary for such description. A dog breeder or a vet may use "Staffordshire Bull Terrier" to describe a breed. To a lay audience, "Pit Bull" may be a better descriptor. Indeed, using audience- or domain-specific technical terminology is an aspect of using a controlled vocabulary. To improve efficiency of text, this concept can apply to the the non-technical terminology as well.

Consider these sentences:

Define the hostname.

Identify the hostname.

Enter the hostname.

Now, enter the hostname.

Each of these sentences means the same thing. We could argue that "identify" and "enter" imply that the name already has been "defined," but will that level of precision be lost on your audience? Will your authors understand it and apply it consistently? The slight differences in wording in these four sentences would require four translations and, worse, could result in differences in meaning in the translated sentences. These inconsistencies in terminology would likely result in additional translation costs and other issues, as Val points out. Even without translation, a reader may waste time trying to determine the differences among these sentences or may interpret them differently. Efficiency requires consistency.

Controlled vocabulary is important not only for technical terminology but also for all terminology within your organization's technical content. Using a controlled vocabulary improves consistency, creates efficiency in the written product, and leads to more effective content.

More Software for Info Dev

Another installment in a series of posts about software applications that can make the life of an information worker a bit easier. The previous posts discuss tools for authoring, publishing, developing graphics, recording and editing video, and managing bibliographies.

Here is another "helper" application to add to your toolkit.

Screencasts

• Screenr

  Screenr is a free, web-based screen recorder. It makes it quick and easy to record and publish screencasts or webcasts.

  Once you've planned and prepared the content for the screen presentation, recording it with Screer is a matter of sizing the screen-capture box around your screen, clicking record and then stop, and then logging into Facebook, Twitter, Google, or Yahoo to publish the results. You can record audio simultaneously. That's it!

  The binary simplicity of creating screencasts with Screenr is a refreshing change from the (sometimes unnecessary) complexity of using "professional" tools. Of course, the results reflect the simplicity. If you are going for studio-quality, have more than drag-and-drop or screen navigation complexity, or require audio scoring or editing in your screencast, Sreenr is not the tool for you. But if you're moving with the current trend toward non-studio quality, "quick and dirty," personal webcasts or if you are creating quick demos for in-house use, for proof of concept, or for blogs, Screenr may provide what need.
  

  Screencast is a great tool for making quick, free, short screencasts.

  
  

  Vendor: Articulate
  Cost: Free as of this writing
  Available: www.screenr.com
  Platforms: Microsoft Windows XP, Vista, or 7, Apple

I'll keep posting my favorite tools here. If you want to contribute to the list, let me know. As always: Your mileage may vary.

This is the second in a series of posts about software applications that can make the life of an information worker a bit easier. The last post discusses some graphics and authoring/publishing tools. Here are a few more "helper" tools to add to that list.

Video

• Camtasia Studio

  Camtasia is a screen video capture and editing program. Camtasia is a handy little tool to create demo videos, tutorials, and teaching aids. Audio can be recorded simultaneously or later as a voiceover to add narration to a video.
  

  Like most video edting programs, this one is a hog. You'll need a GHz of processing power (3 GHz for PowerPoint) and 500 MB - 2 GB of memory. You'll also need a whopping 60 MB of disk for the application alone, plus much more for your raw and rendered files. You also need a separate microphone for audio recording.
  

  One last thought: Video recording is not for everyone. It is time intensive (often with 3:1 or larger ratio of production time to play time). If you are a perfectionist, that ratio will be even higher as you bog down in editing.

  Vendor: TechSmith
  Cost: About $300 ($180 academic version) as of this writing
  Trial: 30-day trial is available
  Platforms: Microsoft Windows XP, Vista, or 7, Apple

Research & Review

• Adobe Acrobat Reader X

  Finally! Although I have my Adobe Professional for the "heavy lifting," Adobe finally has come out with a Reader that allows text highlighting and comments. Not only have I used it daily since I downloaded it, I also suggest it to my students for their readings and research.

  Vendor: Adobe
  Cost: Free
  Platforms: Multiple



• EndNote

  This bibliographic management tool is one of those things that you don't know you need it until you use it. It's a godsend to researchers and writers who cite sources frequently (and frequently cite the same sources). I wonder how I ever lived without it. The limited-functionality EndNote Web version is free for academia. The more advanced features come in the desktop version, which supports features such as library sharing, PDF source linking, and publication list management. There is a Cite-While-You-Write plug-in for Word (in both versions). If you're stuck in Purgatory writing technical, long, or complex documents in Word (as many of us are), at least you can have a glimpse of Heaven in creating your in-text citations and reference list. You also can import any citations created directly in Word into EndNote.

  Vendor: Thompson Reuters
  Cost: About $300 ($116 for a student version) as of this writing
  Trial: A free trial version is available; EndNote Web is free for academia
  Platforms: SAAS, web-based (the full version runs on your PC)



• SurveyMonkey

  SurveyMonkey is a tool to quickly create, deploy, collect, and assess surveys. Like EndNote, SurveyMonkey has a free, limited version and a full version. The full version has some sophisticated features that make it a worthwhile purchase if you do surveys more than once in a blue moon. Although the Google survey tool is fine for many simple surveys, SurveyMonkey has far superior analysis tools and can create more complex surveys.

  Vendor: SurveyMonkey
  Cost: About $200-800 annually as of this writing
  Trial: A basic version for 10 questions and 100 responses is free
  Platforms: SAAS, web-based

I'll keep posting my favorite tools here. If you want to contribute one, let me know. As always: Your mileage may vary.

Disclaimer: Microsoft Word is a tool I "love to hate." Even though I may make disparaging remarks about it from time to time, it is the best word processor around, bar none.

Helper Software

Everyone in the content profession has a favorite--or required--primary application set to use for architecting, authoring, managing, and deploying content. I frequently get questions from clients and students about what tools I use. The answer: it depends. In a series of posts, I'll say a few words about some tools that I use frequently.

Today's post discusses some graphics and authoring/publishing tools.

Graphics

• Adobe Illustrator--for its sophistication as a drawing tool for complex illustrations and for its relatively clean import of files output from CAD programs


• PaintShop Pro--for its ease of use for simple drawings, screenshots, and graphic format conversions

Authoring

• Interleaf--for its sophistication and power as a technical publishing tool. Sigh. Interleaf, at least when I last used it at IBM, is an intuitive, full-featured technical authoring and publishing tool. It has fallen out of favor in the USA because of its high cost "per seat." However, many technical communication teams in India still use this tool (illustrating the fact that a better tool leads to improved productivity and, thus, reduced costs). A great feature of Interleaf is its "documentation set/library" feature. An author can apply formats, conditions, and so forth to an entire library of documents in one fell swoop. Interleaf plays well with SGML and its modern subset, XML.



Interleaf is the "gold standard" for technical authoring and publishing.



• Adobe FrameMaker--for, well, just about any technical authoring, input, and output formats. Three of the significant strengths of FrameMaker are part of its very concept ("frames"). FrameMaker has long implemented a kind of structured authoring; that is, the content and the format are (mostly) separate. This is, by far, the most important feature of the application. Design and architecture experts can create the "format," writers can author the content, and editors can apply (or reapply) the format--all without stepping on each other (much). What FrameMaker has lacked, though, is the content management piece. Authoring in the DITA model can provide additional separation of content and format, paving the way for reusable and repurposeable content. A second great feature is import by reference (think links). The value of importing objects by reference instead of embedding them becomes apparent when working with a large, dynamic graphics database and with large graphics files. Maintain the graphics in a separate database and update them as needed; they will update automatically in FrameMaker. Note that this is not the same as dynamic content. The source still must be published to the desired output type. The third feature that is noteworthy is the "book" concept, which allows one to create custom documents from the same content simply by building a different book. Unfortunately, format templates can be applied from within a book, which is great, but they attach to the chapter/section files themselves. To use different formats, the templates must be reapplied rather than simply specified for a build.



To support multiple output formats, multiple "chapter" book-paradigm content, engineering documentation, the level of detail and control required for regulated industries, and standards-compliant content, FrameMaker continues to be the best technical publishing tool out there.



• MadCap Flare--for XML-based technical authoring and publishing. The MadCap suite of tools focuses on outputs: web, print, and mobile. In situations where there are few legacy documents, smaller documents, and a lessened focus on standards and style compliance, a "modern," XML-based authoring environment is the way to go.



MadCap is a great modern tool to use for multi-channel support, particularly with its addition of mobile outputs.



• Microsoft Word--for its pervasiveness. It is part of the basic Office Suite on virtually every Wintel system and available as a free download to practically every university student in the USA. This "free" price can be misleading, though. What is the lost-productivity cost of trying to make the tool do things for which it was not designed? The 2010 version has some improvements in the equation editor and a few other areas. There are many aspects of technical publishing that you can make work in Word--sort of--but you may have a few choice words with Word along the way. I believe my first workplace expletive resulted from trying to get Word to correctly number paragraphs. Word has a "master document" feature to handle the book or multiple-chapter document paradigm. It can be made to work, generally. And forget about reuse in the proper sense: the format and the content is tightly coupled in Word, although the Styles and design features continue to improve with each iteration.



Word is not a technical publishing tool, but it is a great word processor that everyone has.

There are many more tools that I use weekly or even daily, some complex or specialized, some more prosaic but no less useful. These posts peek under the hoods of geek-toys in my professional garage; your mileage may vary.

Disclaimer: Many of these are Adobe tools. That's not because I love Adobe so much. In fact, I use their software in spite of the often poor customer support and decidedly non-friendly attitude toward software for education.