Technical Communication Camp

Styles – Why use them?

In Doc-To-Help, you apply Styles to your Source documents so that your Target output will look and behave the way you prefer.

That's one good reason to use them, but not the only one.

Another very good reason is because Styles enforce consistency. If you create a Style for highlighting items in your user interface (for examples, toolbar buttons, dialog box names, windows, etc.) and that style uses a specific font, font color, and it's bold – you can name it "UI Element" and you and everyone on your team can use it. OR you could write up a post-it note to remind yourself that UI Elements are Verdana + dark blue + bold. And then send everyone on your team an email that lets them know this is the standard (or note it in your Style Guide).

But when you apply local formatting (AKA "in line" or "ad hoc" formatting) without using a Style, you don't have a standard. You simply have a guideline. And it is easy to forget guidelines.

In addition, if you had created a Style in the first place, you could easily change what "UI Element" looks like by updating the Style. If you want to switch from dark blue to green, you simply update the Style. You don't have to comb through all of your source documents and fix each UI Element individually.

That being said, you can choose *not* to use Styles ... in that case you can use the Formatting buttons in all three of the editors in Doc-To-Help. If you are using Word, most of them can be found in the Formatting toolbar (Word 2003) or the Font and Paragraph ribbon groups in the Home tab (Word 2007). In Adobe Dreamweaver and Microsoft FrontPage, you will use the Formatting toolbar (FrontPage) or the Text menu (Dreamweaver).

In the Doc-To-Help XHTML editor, you will use the Formatting ribbon group on the Editor tab.

In the XHTML Editor, there is a slight difference between the buttons to the left of the Local Formatting button, and those to the right, however. The ones available to the left of the Local Formatting button (bullets, numbering, bold, italic, subscript, superscript, and more) may be applied to your document and the document will still conform to the W3C XHTML 1.0 Strict Specification. This is because those options are part of that specification. If you click the Local Formatting button, additional options for applying formatting without styles will be revealed. These options are: font name, font size, text align left, text align center, text align right, text align justify, highlight color, font color, underline and strikethrough. If you use these options, your document will no longer conform to the W3C XHTML 1.0 Strict specification; it will switch to the Transitional specification.

Just a note before using the Local Formatting button …. If you use Local Formatting options (font name, font size, text align left, text align center, text align right, text align justify, highlight color, font color, underline and strikethrough) then turn off Local Formatting by clicking the button, all of the formatting applied with the local formatting options will be removed, returning the document to the Strict specification. 

Creating renewable content – “Green” authoring

Those who adopt “green” lifestyles try to recycle and reuse as much as possible, preserving resources for future generations.

By the nature of what we produce, Tech Comms can't create content that will last for generations to come, but we can create content that is "green" by adopting reuse strategies. And writing once and reusing many times is not only efficient, it cuts down on errors.

One of the best ways to create reusable content is to save content “chunks.” These chunks can be long or short and they have two added benefits:

• The content only needs to be updated in one place, no matter how many times it is used within a project.
• It ensures consistency, since core information will be the same within and among projects. 

To chunk your content in Doc-To-Help, you would use Variables. I’ll discuss how to create and use variables in Doc-To-Help in a minute, but I did want to note that determining what information to “chunk” into variables is the most time-consuming part of the process and takes a bit of up-front planning and design. Once you have finished planning, the creation process is simple.

To get started, take a look at your content and determine what pieces are used over and over. Some common software documentation examples:

• Product Names
• Field/checkbox/other UI definitions
• Product descriptions
• Terminology definitions

After you’ve sorted out what content you can reuse, create a list of everything that needs to be “greened.” You can then determine what type of variable each will need.

For very short pieces of content, use Text Variables. These are great for things like product names, because if the name changes at the last minute, updating is easy.

For longer chunks that may require formatting, Rich Content Variables are the way to go. They are ideal for definitions that are used repeatedly, and also for lesser used, but volatile information, such as product descriptions.

Once you have determined what you will reuse and how, you can get started chunking. You probably won’t have to do too much writing, because the material already exists. Some rewriting to merge like information may be in order. This recycling exercise will give you and your team the opportunity to update information that has not been reviewed in a while. So you’ll be increasing efficiency, and improving content at the same time.

Now to creation. Before you begin, think about naming conventions. It’s important to give Variables meaningful names, and when creating Rich Content Variables, make sure to divide your Variables into different documents that are also well-titled.

To create a Text Variable:

1. Open the Variables window (On the Project tab of Doc-To-Help, click the Variables toolbar button. )
2. In the Text Variables area, click on the Add New Variable toolbar button. An editable field named "New Variable" will appear in the Name column.
3. Enter a name for the variable, then double-click "Variable text" in the Text column to enter the text (one word or more).
   If you’d like, you can assign one or more conditions to a Variable, so that it is only used in certain outputs.  

To create a Rich Content Variable:

1. Open the Variables window. 
2. In the Rich Content Variable area, click on the Create New Document button. Choose XHTML, HTML, or Word Document from the drop-down list. The Save New Document As dialog box will open. Enter the document Name and click Save to add it to your project.
3. Double-click on the document name in the Variables window to open it. The Variables document will display a table with two columns.
4. Enter variable name in the column on the left (avoid spaces), and the variable content in the column on the right. Apply styles as desired, including conditions.
5. Save the document.

Using Variables is easy … to insert variables in documents:

At the appropriate place in your source document, select the text that will be replaced by a variable and click the Variable button. Choose the proper variable from the list in the Variable dialog box. It is a good best practice to use the variable name as the placeholder text.

(In Microsoft® Word, Microsoft® FrontPage®, and Adobe® Dreamweaver® documents the Variable button is located on the Doc-To-Help tab or toolbar. In the XHTML Editor window,  the Variable button can be found on the Insert tab.)

For more on Variables, see Creating Variables.

For more on Conditions, see Utilizing Conditions.
 
After you have created and are using your Variables, make sure to document your process and your variable naming conventions so that any new content is authored “green.”  

Have fun creating “content that survives” with Variables.

What you can do with the Doc-To-Help Ribbon in Word

 This is the final of a three part series called "How do you like to write?" This post focuses on the Doc-To-Help ribbon in Microsoft® Word.

This ribbon (or toolbar, depending on your version of Word) appears in all Word documents that are included in your Doc-To-Help project. It allows you to create links, mark text as conditional, add variables, and more -- right within your Word document.

These features are useful for many reasons:

• Creating navigation (Link button)
• Customizing output (Conditional Text button)
• Reusing content in multiple places (Variables button)
• Adding index entries (Keyword button)
• Other handy options, such as inserting a Flash movie, creating an image map for a graphic, adding a term to the Glossary, adding margin notes, are all here.

You may not need all of these features for your project, but you'll find many of them extremely useful for creating a robust project – while never leaving your writing workflow.

And, once again, you are writing a book, but still generating individual topics that transform into both logical Help and Manual output. And those same topics can be used in multiple Targets to create as many variations as you need.

Tips for Writing a Book, But Generating Logical Help

In my last post (How do you like to write?) I discussed how Doc-To-Help makes it simple for you to write a book, chapter by chapter  — and still output high-quality, feature-rich, *logical* Help and web output, as well as attractive manual output. In this post; a few writing tips... 

If you follow certain guidelines when you are writing, the online output generated from your Word Documents will be logical and consistent, while not compromising your writing flow.

If you are writing software documentation, standardize on a consistent heading (such as “Using the… Screen”) which makes sense in both the book and help. Since your heading will become a topic in online outputs, also design a consistent structure for each topic that you will later map to Help buttons*. For example:

• Title 
• Introduction
• How to access the screen/dialog
• Task(s)

Be sure to cover all the main points in under one heading, so that that a single topic will work for each dialog box.

• Standardize on one (at most two) Heading styles that Help button topics will map to. It can be confusing to the user if multiple styles appear from Help buttons.
• Never use the word “chapter” or any other word specific to books. (For example, “page” “topic” “help system” “manual”) “Section” is a good substitute.
• Use “See *Insert Link*” rather than “See below,” “See above,” etc.

* This mapping is done using context IDs. See Implementing Context Sensitive Help.

Next time ... The Doc-To-Help toolbar in Word.

How do you like to write?

With music blaring on your iPod? In a quiet corner? Actually, that's not where I'm going with this (although I admit I don't write and listen to music at the same time). I'm talking about something a little more fundamental. Do you like to write in a traditional narrative format?

If so, Doc-To-Help makes it simple for you to write a book, chapter by chapter  — and still output high-quality, feature-rich, *logical* Help and web output, as well as attractive manual output.

And if you'd prefer to write discrete content chunks, you can do that in Doc-To-Help also using the built in XHTML Editor or an HTML editor (such as Adobe^® Dreamweaver^® or Microsoft^® FrontPage^®). You can even combine different types of documents in the same project. More on this in a future blog post.

But back to writing preferences … With Doc-To-Help, you can work in Microsoft^® Word, writing in an organic way, and Doc-To-Help takes care of the rest. You can write a book that flows, but transforms into logical Help topics. And you don't need to create separate topics – because Doc-To-Help creates them for you.

Writing in Word, Creating Help and Manuals Automatically

How does this happen? First of all, Doc-To-Help automatically breaks your Microsoft Word documents into individual topics based on Heading styles. It then uses the order of those topics to automatically structure the navigation of online outputs. If your documents have logical structure, so will your Help and web output, right out of the box.

Here's an example:

You write a chapter and apply the Heading 1 style to the chapter name. To the name of each section under that chapter, you apply the Heading 2 style.  Each chapter can be a single Word document, or you can keep multiple chapters in the same Word document. Just use the Heading 1 style to designate the start of a new chapter.

By design, Doc-To-Help does the following when you build your output (manual, Help, or web output): Heading 1’s in your Word Documents automatically become parent topics, and all of the Heading 2’s under them become subtopics. This can be illustrated by looking at the automatic Table of Contents generated by Doc-To-Help. The automatic Table of Contents for both online Help and manuals is generated based on the structure of your documents, and their order in the Doc-To-Help Documents Pane.

Note that Heading 1's with no Heading 2's under them become "standalone" topics in the TOC. (You can customize the automatically generated TOC if you would like.)

Your online Help and Manual TOCs will be appropriate for each format.

Parent topics (Heading 1's) automatically include “See Also” links to their subtopics (Heading 2's) in online outputs. You can add additional "See Also" links manually, and the introductory text (More:) can be changed and its style customized.

 

There are a few other ways Doc-To-Help automates a "book" workflow:

·      Links to other topics (created in Word using the Link button on the Doc-To-Help toolbar or ribbon) will automatically become cross-references (with page numbers) in your printed manual, while they will become hyperlinks in online outputs. You don't need to use Word's cross-reference feature to get both.

·      Margin notes in your Word Documents automatically become pop-ups in online Help or web output.

And …  Doc-To-Help automatically generates the Title Page, Table of Contents, and Index for printed manuals, so you don’t have to. It also adds footers. You don't need to use Word's features to create them. Just write and then build your Manual Target.

Next posts: Tips for Logical Help and the Doc-To-Help Toolbar

Until next time ... 

Upcoming Talks on User Assistance

Just a quick laundry list of my upcoming talks about User Assistance ... hope to see you at one (or more) of these events!

DocTrain West March 17-20 http://www.doctrain.com/west/

• All-Around User Assistance:Delivering Layers of Information Efficiently
• Improving User Assistance Using Journalistic Principles

WritersUA March 29 - April 1 http://www.writersua.com/

• Embedding Dynamically Updated Help into the User Interface Using a Dedicated Help Pane and Custom Control (Peer Showcase)

Society for Technical Communication (STC) Summit May 3 - 6 http://conference.stc.org/

• Designing and Implementing Embedded, Dynamic User Assistance

Be sure to visit the ComponentOne Doc-To-Help booths at WritersUA and STC. In fact, if you are attending WritersUA, check out Doc-To-Help Day.

See you soon!

New Doc-To-Help Articles on DynamicHelp and more ...

I've recently written three new articles that you may find helpful and posted them to our knowledgebase, HelpCentral. HelpCentral also has videos, FAQs, and other helpful information. Here is a quick article overview ...

• If you would like to include embedded Help with your product, but couldn't because of the time and complexity involved, you may find the ComponentOne DynamicHelp control the solution you have been looking for. This control can be incorporated into the user interface of any application developed in Microsoft Visual Studio.NET, and the mapping of the interface to the Help file can be completely managed by the Information Development team -- no Context IDs needed (but you can use them if you'd like).
  See Creating Embedded Help with the ComponentOne DynamicHelp control
  
  
• One of the coolest features of Doc-To-Help is the automatically-generated “blue buttons” (AKA "Auto Subtopic Links") that appear at the bottom of Help topics. This article explains how to edit the Heading text, button graphic, and link text to your liking.
  See Changing the Look of Auto Subtopic Links
  
  
• You can change the look of your Help "skin" (or Theme) in Doc-To-Help with the Theme Designer. This article explains how to swap out the default logo (as well as its link and pop-up text) in a Theme.
  See Changing the Doc-To-Help Logo on a NetHelp Target

Happy Holidays and Enjoy!

A few of my favorite (web) things

It has finally stopped raining in Pittsburgh (for the moment) so I'm going to blog while the sun shines.

I love the 'Burgh, but it does rain quite a bit in June. We have a large arts festival -- the Three Rivers Arts Festival -- that coincides with the rain every year. But it all seems to work out.

So ... here are a few of my favorite (web) things ...

• You can build your own fonts (and share them) with FontStruct http://fontstruct.fontshop.com/ (I read about this @ http://www.slate.com/id/2192535/)
• The Duck Island Greeking Machine generates greeked text in seven "languages" (Classical Latin, Hillbilly, Marketing, The Matrix, Metropolitan, Pseudo German, and Techno Babble). Very handy. http://www.duckisland.com/greekmachine.asp
• If you need to map colors for different outputs, the Tridesign PMS/RGB/Hex color (actually colour) chart is very useful. http://www.tridesign.com.au/index-tess1.php?ItemNo=2055

While on the subject of the web -- I highly recommend Janice (Ginny) Redish's new book Letting Go of the Words -- Writing Web Contents that Works. Lots of great information and solid examples. I have post-it notes all over my copy.

Lastly, an interesting article from slate.com about how we read online http://www.slate.com/id/2193552/ (Jakob Nielsen is referenced).

More later

Dynamic Help: I’ve got it and you can have it too

I’ve worked on a number of software products, and there were several that were ideal candidates for dynamically updating, embedded help – but since that sort of effort is usually software developer-intensive, I was never able to make it happen (not for lack of trying by myself and some wonderful software developers).

"Camp" on the Road: STC Annual Conference in 10 Days

Since I need to play a bit of catch up; a few updates and thoughts...

Can't think of a better way to kick off summer camp than the STC Summit in Philly. (Full disclosure: I'm currently an STC Director At Large, but I've been attending the Annual Conference for years.) Hope to see you there.

Earlier this month I attended DocTrain West in Vancouver. I did a talk titled "Documentation Planning and Library Design in a Web 2.0 World." I'll be posting more on this subject later. While I was there Tom Johnson interviewed me for a podcast that he will be posting on his "I'd Rather Be Writing" blog. Looking forward to hearing it.

Great Web 2.0 read (albeit from a marketing perspective) -- "Groundswell: Winning in a World Transformed by Social Technologies" by Li and Bernoff.

More later!

Welcome to Technical Communication Camp!