InfoArchitect

Using a Controlled Vocabulary

2011-06-12T12:39:00.019-05:00

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

2011-06-09T09:43:00.008-05:00

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.

2011-03-25T11:55:00.021-05:00

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

2011-02-01T11:23:00.031-06:00

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.

Conga!

2009-09-18T08:50:00.023-05:00

Ok. I know what you're thinking: "Jazzy song for a Friday morning. But what does it have to do with IA?"

Gloria Estefan's "Conga" is great way to get a jump-start on the weekend, no doubt. But dance also provides a lesson for information architecture.

I've been interested in dance since I watched old musicals on late-night movies as a kid. In fact, I wanted to grow up and dance like Fred Astaire. Now, I appreciated Ginger Roger's smooth, graceful, moves -- and her ability to do everything her partners did except in heels and backwards. But it was Fred Astaire who really awed me. And when he danced with the hat rack and appeared to dance on the ceiling in "Royal Wedding," I knew I had to learn to dance like Fred Astaire. I practiced incessantly -- once even managing to leap atop a kitchen chair back and rotate it on one leg. Once only. The wall behind the kitchen table, the chair, and my body suffered from many attempts. Outside the chorus in a high school version of Camelot, I never did dance. But I did learn something from those hours on end of trying to imitate Fred Astaire's inimitable moves. First, most things require practice in order to do them well. And second, small improvements are both important and satisfying.

Let's talk about the this second idea with regard to information architecture. It is ideal to completely identify all of an organization's information before beginning an architecture. That is, identify and then map out sources, topics, articles, audiences, audience, areas for growth, authors, SMEs, contributors, goals, etc. etc. etc. Ideal. However, unless your organization is brand new and has a very small, manageable amount of information and yet a clear idea of the organization's near-term and long-range goals and direction, it may be impossible to identify, much less gather, all of your information. Furthermore, work does not stop and therefore information flow and creation does not stop during IA exercises. So unless your organization has deep pockets and exceptional content management practices, these sorts of "forklift" IA exercises with a goal of creating a completely new information architecture while maintaining current operations are difficult. That's not to say that they are impossible, but they are impractical for most small to medium organizations.

What is more practical is to expect small, continuous improvements. (Sound familiar? Continuous improvement is the hallmark of the Kaizen movement that spread from Japan to the US via the work of W. Edwards Deming. Continuous improvement also is the goal of dancers and other creative types when they "practice, practice, practice.") Continuous improvement (CI) requires standardization first, then measurements of performance and improvements of the standardized processes. An argument against this method is that because CI always measures against the standard, it does not allow for creative leaps of inventiveness in the process or product. In information architecture, however, the new architecture is already a creative leap.

A good IA approach does not (necessarily) replicate what you have now, but provides an architecture that works: it is appropriate for your goals, objectives, current work, and future plans. The key to a successful architecture for many organizations is to build one into which your existing data can be managed as is and migrated into the architecture over time while allowing new information to be created so that it makes full use of the new architecture.

A wonderful measurement to use for success of an IA implementation is usability -- and not only for your customers or external audiences but also for the folks who contribute to your knowledge base. Wikipedia has been in the news this month as it celebrates its 5-year anniversary. Wikipedia was begun on September 7, 2004. As the History for the site says: "The early history of Wikipedia was characterized by much chaos and well-meaning strangeness." Over three million articles in more than 100 languages strong and virtually every college freshman's first search source, Wikipedia did not exist five years ago when the Fall semester began for many colleges and universities. Had Wikipedia not taken the continuous improvement approach, it would have died out with the anguished cries of college professors who cried out for students to use academic sources. (Students take heed: Wikipedia still is not a vetted source; rather, it is a good source of additional sources and for a quick overview.) This brings us to a second measurement for IA success: content integrity.

The quality, completeness, and appropriateness of content is what I mean by content integrity. And the best IA structure in the world does not guarantee content integrity. Early Wikipedia articles are the poster-children for excellent IA and poor content -- which with practice and CI became better. However, a successful IA will be able to make the best of content, fully utilizing, linking, and cross-referencing content for easy search and retrieval. The rest? Producing excellent content requires excellent writing. That's a talent that's up to the authors and editors. And I'll save that conversation for another day. Right now, I'm off to practice my conga with Gloria...

Inserting Audio Comments into a Word File

2009-04-18T21:58:00.007-05:00

A colleague asked how to insert comments into a Word file. I realized that I didn’t know, so I did a little research. It turns out that it is quite easy. All you need is a microphone and Microsoft’s built-in tools.

You can either insert pre-recorded comments or comment on the fly. Use your favorite audio recording software or the simple Sound Recorder included with the Microsoft operating system at Start → Programs → Accessories → Entertainment → Sound Recorder.

How to Insert an Audio Comment

1. Click Insert → Object.

2. To insert a comment…

a. that has been pre-recorded: Select the Create from File tab and then browse to and select the pre-recorded file.

b. on the fly: Select the Create New tab, select the object type (Wave Sound, for example), and then record the comment.

3. Save the file (with a new name).

That’s it! Easy as can be.

You can also save the .doc file as a single web page (.mht) and preserve the audio snippets.

The caveat is that inserting sound files makes the file significantly larger. I started this little Word document test as text-only, at about 11 KB. After adding two very short comments, the file is 548 KB. You can see how this could get out of hand quickly. Zipping the file compresses it somewhat. I got about a 25% savings in this file. Your results will vary depending on how much text, formatting, graphics, and audio are in the file. Rather than insert several small clips, it may be a good idea to consolidate all of your audio comments into one file.

In any case, it is not only possible, but also quite easy to insert audio commentary into a Word document file.

Happy commenting!

Freelance Anthem

2009-02-16T00:03:00.004-06:00

For a bit of comic relief, enjoy the "Freelance National Anthem" lyric by Bill Dyszel, sung to the tune of "Ode to Joy." Dyszel's lyrics available at www.youtube.com/cinemasolo.

Wireframes for IA

2008-10-26T20:05:00.008-05:00

What the heck is a wireframe?

Recently, someone asked me about wireframes. In short, wireframes are a low-cost, quick way to rough out the architecture of web sites, structured documents, document sets, training courseware, marketing collateral, web-based applications, and systems. Some other buzz words that may be used interchangeably (though not always correctly) with "wireframe" are low-fidelity mockup or rendering, schematic, page architecture, template, diagram, blueprint, or zone diagram. Grey model and story board also are used sometimes for procedure and task sequence mockups.

Wireframe techniques work for any sort of structured content. Think outline, but better. Wireframes can be used to convey many different aspects of architecture, but the data most often captured in wireframes are:

Content at a high level
Relationships among content
Structure of content (innate hierarchy)
Structure of relationships (structured hierarchy for presentation)
Navigation and flow

Subject matter experts and information developers provide the content inventory, detailed content, user profiles, and use-case scenarios for a project. Using these and working with the SMEs and information developers, the information architect creates the site map and the wireframes. A wireframe is not intended to be a design document, but an overall snapshot of the architecture of a project and its content. The IA also works with the designer, who provides the design deliverables for the project. It is not unusual for an IA to take on the design role as well, but creation of the style guide, templates, page layouts, and other design considerations are separate from creation of the wireframes. Wireframes range from a very abstracted level, providing only high-level information, to extremely detailed, including content and intricate procedures.

Creating, reviewing, and amending wireframes does add work to a project. However, early (and frequent) wireframing and approval up front generally will save hours, if not days or weeks, of rework later. Wireframes can be created using a variety of tools, including PowerPoint, Word, Excel, FrameMaker, Visio, and custom tools provided for use with a particular development application.

One last thought: Don't mistake simple wireframes for simplistic ones. Some of the simplest wireframes are the most powerful. A simple and quick wireframe set can provide an early snapshot of a project's architecture, when it is still relatively easy and inexpensive to make changes. A widely-available tool (like PowerPoint) is accessible to almost everyone, everywhere, making it easy to distribute and review a set of wireframes. Distributing wireframes in PDFs or another universal format is also an alternative, and may enable the IA to use a custom wireframing tool.

Welcome

2008-06-05T19:47:00.001-05:00

Welcome to my blog. Periodically, I will post my musings here.