The Changing Face of Technical Publications: Aberdeen Group's Topic-Based Authoring and Customization Strategy Guide

Often conflicting pressures to produce communications that better fit customer demands as well as stay within tightening constraints on budgets and schedules are leading many technical communications organizations to a topic-based approach to authoring. In fact, 58% of participants in Aberdeen Group's October 2008 DITA and the Technical Communicator’s Transformation study report that they currently follow author content in a topic-based manner, with a vast majority of those remaining planning to implement one in the future. A topic-based approach promotes greater content reuse and is seeing a considerable impact on the authoring efficiency of technical communications projects today. The benefits of topic-based authoring can be compelling, with findings from the The Technical Communicator’s Transformation study indicating that when pursued the right way, topic-based authoring can have a broad range of benefits, enabling an organization to meet authoring and localization cost targets as well as documentation quality expectations, among others. However, as the adoption of this approach spreads, the advantages seen by today's leading organizations will flatten out. This Sector Insight provides a guide for current adoption of topic-based authoring and those still considering it; outlining the changes that are expected to take place in as topic-based authoring goes mainstream.

Jackson, Chad and David Houlihan. Aberdeen Group (2008). Resources>Documentation>Information Design>Technical Writing

Unstructured Documents in Structured FrameMaker

A few days ago, there was a thread on the Framers mailing list regarding working in the structured FrameMaker environment. Someone commented that editing unstructured documents in the structured interface does not affect the unstructured documents. I found this to be untrue recently.

Scriptorium (2008). Articles>Document Design>Information Design>Adobe FrameMaker

Good Designs Have Strong Contrast

Push contrast more than you might be naturally inclined. If you don’t, you end up with conflict. The next time you eat at a restaurant, look closely at the menu. A good menu has a high degree of contrast between sections.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Document Design>Graphic Design

Behind the Curtains: Table Styles

Table Styles are my favorite type of Style in Word. They allow you to quickly and consistently format the table itself (e.g. borders, shading, etc.), the content within the table (E.g. line spacing, font color, font size, etc.), and they can also can tell a table when to do these (e.g. shade every other row, bold text in the first column, etc.). The first two enable you to create really rich tables, and the last one (which I'll call Conditional Formatting for the rest of this post) enables you to easily work with those rich tables. Both are quite important.

Microsoft (2008). Articles>Document Design>Style Sheets>Microsoft Word

Why Microsoft's .docx Format is a Good Thing

Here's a simple way to read one of the new Microsoft file formats, even if you have no Microsoft software installed. Let's suppose you have a file that ends with .docx, from the latest version of Microsoft Word. It's actually a zip file, so add .zip to the end and unzip it. You'll find a cluster of files and folders inside, and the one you want should be called document.xml. Double-click that and it will load in a browser window, where you can read the text.

Schofield, Jack. Guardian Unlimited, The (2007). Articles>Document Design>XML>Microsoft Word

Reviewing Wiki Documentation via Crucible

I have been playing around with Crucible, Atlassian’s peer code review tool. The latest version of Crucible allows you to review Confluence wiki pages. This is a new feature, so I decided to try it out. Also, I was wondering why you might want to use an independent tool to review a wiki page, when you could instead just add comments to the page or update the page directly.

Maddox, Sarah. ffeathers (2009). Articles>Web Design>Documentation>Wikis

An Approach to Visually Creating and Editing Nested Compound Document

Currently, visual XML structured authoring applications can typically handle a small number of XML vocabularies. In some cases, they can even handle them in limited nested scenarios. One of the purposes of creating XML documents with compound vocabularies is to present related information on a given topic in different manners (tables, charts, etc). The synchronization of views between objects of different vocabularies in real-time editing helps authors realize this potential. In this presentation we will discuss an approach to visually creating, editing and synchronizing, nested compound XML vocabularies within one document. The open nature of the architecture enables developers to create plug-ins for new vocabularies including the ability to define synchronization. Also this architecture provides simple method to define visualization of a new vocabulary by utilizing plug-ins already developed and activated.

Wake, Nobuaki and Junpei Aoki. IDEAlliance (2004). Articles>Document Design>Information Design>XML

Managing Digital and Print Deliverables for Aviation Data

This paper discusses the rationale and design behind Jeppesen’s single-source publishing system. With the business needs to single-source publishing capabilities becoming more acute, Jeppesen partnered with Astoria Software to develop a solution. The result is a system based on commercial-off-the-shelf software, XML industry standards, and open-source tools.

Jones, Matthew and Bob Thomas. IDEAlliance (2004). Articles>Document Design>Single Sourcing>XML

XML for Creative Content and Page Layout Applications

While technical documentation has traditionally been the domain for structured authoring, there is increasing interest in using XML for more “creative” materials such as sales brochures and marketing collateral. Such pre-sales materials often have even more compelling opportunities for single-sourcing and reuse than technical documents. Up to now, these materials have been produced one at a time in page-oriented publishing systems like Adobe InDesign and Quark. While this provides maximum flexibility in controlling exact page layouts, it can create a nightmare when small changes must be replicated across all the independent pages and documents. Why can’t we use XML to more flexibly handle this kind of content? In fact, we can! Using page formats from real marketing content, this whitepaper demonstrates how XML tools can be used to maintain highly graphical sales collateral, web pages, and product catalogs from a single source of XML information.

Severson, Eric. IDEAlliance (2004). Articles>Document Design>Marketing>XML

Review: FrameMaker 9 Review  

FrameMaker users are buzzing about FrameMaker 9. With CMYK support, CMS integration, DITA 1.1, and PDF commenting, this version is full of new functionality but is unfortunately also buggy and inconsistent. This review covers the most important new features of FrameMaker 9.

Loring, Sheila. Scriptorium (2009). Articles>Reviews>Document Design>Adobe FrameMaker

So, You Want To Screen Capture, Huh?

Here's a quick tutorial about screen captures, thus the title. If you're not sure what a screen capture is, then think about the pages you've seen lately. Maybe some of them have had specific sections of the desktop or a program made into an image. It was almost as if they captured part of the screen as an image.

Burns, Joe. HTML Goodies (2004). Articles>Documentation>Graphic Design>Screen Captures

Why Bother With User Documentation in Recessionary Times?

In recessionary times, organisations should focus on getting sales from existing customers - so customer retention becomes ever more important.

Cherryleaf (2009). Articles>Documentation>Business Case>User Centered Design

InDesign Secrets

If you try to find reliable information about InDesign on the Web you’ll find yourself scouring Adobe’s site or muddling through dozens of other sites for a tip or two. Now that you’ve found InDesign Secrets, it’s time to stop all that muddling.

InDesign Secrets. Resources>Document Design>Blogs>Adobe InDesign

Lessons Learned with Quick Reference Guides: Timing and Truth

I should never fully trust anyone on a project. I don’t mean this disrespectfully, because I work with competent, talented professionals. But no one has the full picture of how the application will truly work. The quality assurance (QA) engineer usually has the clearest picture. The program manager and project manager are often living in a slightly different world, full of a vision of how the product should work and how they expect users to interact with it, but sometimes they’re missing important nuances in the actual implementation. The interaction designer builds prototypes and assumes the developers will build them to spec, but since the prototypes are usually HTML-based, and not in Java or .NET, variances are inevitable.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>User Centered Design>Emotions

Free Microsoft PowerPoint Templates

Our templates are free and we do not offer any kind of support for our templates. You are responsible for editing and modifying the downloaded templates, backgrounds or products.

Kumar, Raja. PowerPoint.in (2009). Resources>Presentations>Document Design>Microsoft PowerPoint

Fluid Grids

Fluid layouts are an undervalued commodity in web design. They put control of our designs firmly in the hands of our users and their browsing habits. They’ve also utterly failed to seize the imagination of web designers.

Marcotte, Ethan. List Apart, A (2009). Articles>Web Design>Document Design>CSS

Bezględnie Względny

Pozycjonowanie z kolei jest jednym z najczęściej mylnie interpretowanych aspektów wersji 2 CSS. Przyjrzyjmy się zatem nieco bliżej temu, jak ono działa.

Olsson, Tommy. Grabun.com (2004). (Polish) Articles>Web Design>Document Design>CSS

CSS Hizalama

Hizalama ise CSS 2’nin belki de en yanlış anlaşılmış bölümlerinden biridir. Şimdi nasıl çalıştıklarına biraz daha yakından bakalım.

Olsson, Tommy. Cnkt (2004). (Turkish) Articles>Web Design>Document Design>CSS

Liquid Layouts the Easy Way

This article explains one method of achieving a successful liquid layout as well as providing basic definitions of liquid, fixed-width and em-driven layouts.

Weakley, Russ. MaxDesign (2003). Articles>Web Design>Document Design>CSS

How to Format Your Technical Documents Consistently With a Template

Consistency of a technical documentation is what creates that subliminal sense of trust and confidence in the end-users. Someone once quipped: “it ain’t technical documentation if it ain’t boring.” This of course is not true since I always found technical documents very interesting indeed. I’m the sort of geekish person who can marvel at a well-designed user’s manual for hours and appreciate its beauty and all the effort and thinking that went into its production. I imagine how happy people would be when they use that manual and solve their problems and that, believe it or not, makes me happy as well. That’s the main reason why I’m in this business.

Akinci, Ugur. Technical Communication Center (2009). Articles>Document Design>Style Sheets>Technical Writing

Wurman’s LATCH Model of Information Organization For Technical Documentation

Technical writing has its mechanical aspects that need to be mastered. A good technical writer must know how to use English effectively as well as various software products to produce acceptable technical documents. But I wish technical writing were all about that. The hardest part comes before one even sits down in front of a computer to type the first word. The hardest part in documenting anything is organizing the information in a way that makes sense from the user’s point of view. Otherwise a technical document suddenly looks irrelevant.

Akinci, Ugur. Technical Communication Center (2009). Articles>Information Design>Documentation>Technical Writing

How to Structure FrameMaker Paragraphs While Using the Unstructured Interface

Using the structured features requires advanced training and you probably won’t need them anyways unless you’re doing any “single sourcing” (which is the topic of yet another article). For example if you were doing any XML-based authoring or “database publishing” then you would definitely need to learn how to use the FrameMaker’s structured interface. However, there is an easy way to imitate structured documentation while you are still in the unstructured mode. This is one case in which you can have your cake (unstructured FM) and take a bite out of it too (by enjoying one selected feature of structured documentation).

Akinci, Ugur. Technical Communication Center (2009). Articles>Document Design>Technical Writing>Adobe FrameMaker

Seven Time-Tested Principles to Design a Cover For a Technical Document

Here are seven time-tested design recommendations culled from my 20 years of experience as a professional writer, page layout and information designer.

Akinci, Ugur. Technical Communication Center (2008). Articles>Document Design>Technical Writing

How to Create a New Paragraph Style in a FrameMaker Document

Adobe FrameMaker is the information design platform of choice for most professional technical writers and technical communicators across the globe. Like all powerful software applications, FrameMaker also has a lot of features and configuration possibilities. One of those features is the ability to create new paragraph styles. Each paragraph style in FrameMaker is represented by a “Paragraph Tag.” So to create a new formatting style you actually create a “tag.” Here is how you can create a new paragraph style/tag for your FrameMaker (FM) document.

Akinci, Ugur. Technical Communication Center (2008). Articles>Document Design>Style Sheets>Adobe FrameMaker