Tech Write Tips

October 16, 2006

Flare 7: File List

Filed under: Information Types,Madcap Flare,Technology,Tip,Tool — AndyR @ 12:09 pm

filelist.gifFlare 2.0 further substantiates the breeding we have come to expect from the Madcap stable. This version introduces new features and beefs up performance. This is the first of a few posts that will focus on different features of Flare 2.0.

Today we address the new File List pane, available by selecting View | File List from the menu. As with all components of the Flare interface, this can be positioned to provide easy access as is appropriate to your working style.

The File List pane enables you to view all the files in your project in one list. This list can then be ordered and filtered as required. at first this doesn’t seem all that significant, but when combined with other components of Flare’s flexible interface it enables a number of productivity enhancements.

  • Image Pallet: By filtering the list to include images (*.gif; *.jpg) you can use the list as a source of images for your topics. Rather than having to browse to the required image you can simple drag-and-drop the image from the File List to the topic. Ensure you drag the image icon rather the the text.
  • Edited Files Pallet: By filtering the list to include html files (*.htm; *.html) and ordering by Date Modified you can use this as an unlimited recently list list. This complements the File | Recent Files menu, as it provides a longer list and potentially quicker access to the files.
  • StyleSheet Management: By filtering the list to include html files (*.htm;*.html) you can view the style sheet in use by each topic. Order the list by Style sheet to group the different style sheets together. This enables you to weed out old style sheets and ensure all topics are on the latest version of your style control.
  • Condition Management: By multi-selecting a collection (hold CTRL) or range (hold SHIFT) of topics, right-clicking and selecting Properties from the pop-up menu, you can specify Basic, Topic, Conditional and Language properties on multiple topics. This is particularly useful when managing conditional topics. You can also use the list, ordered by conditions, to further assist the management of conditional topics.
  • Topic Type Editing: By filtering the list by a particular file name you can edit a certain type of topics. (Assuming you have consistently named your topic files) This enables you to rename and edit these topics to ensure they are consistent. For example, filter by ‘*about.*’ to work with all the about topics.

All-in-all the File List pane provides some excellent additional ways of working. Once it includes the ability to view which topics are in the TOC and Index, and filter by folders it will become a key way of working with Flare 2.0.

July 11, 2006

Best Practice: Flare 2 – Automated Themed Topic Types

Filed under: Best Practice,Future-proofing,Information Types,Madcap Flare — AndyR @ 12:38 pm

As we suggested in our previous topic types post, to ensure you are ready for future help formats it is advisable that your topics provide information in clearly defeind types. This post considers how you can present these topics in an HTMLHelp in such a way that it is clear what sort of information is being communication.

Topic Titles
The first step in this task is to ensure that you have consistently named your topics, as we discussed in our delicious topic title post. You need to define a set of rules that specifies how you name your topics and then stick to it.

One rule could be to always title concept topics ‘Concepts:…’. Another might be to always include the control type in your software screen focused topics, for example ‘Select Window’, ‘Open Frame’ or ‘Close Tool’.

Dynamic Header
The next step is to include a .js file in your Flare project to output content at the top of your topic. It is advisable for this to be directly after the <Body> tag, and referenced as follows:

<script language=”JavaScript1.2″ type=”text/javascript” src=”Head.js” mce_src=”Head.js”></script>

Detect Topic Type
This head.js javascript then need to interrogate the title of the html file, (document.title) then check it:

  1. If it contains concepts, then output a concept header.
  2. If it contains Window, Frame etc, then output a software control header.
  3. Otherwise output a procedural header.

The content of the header will need to be output with the following javascript:

document.write(‘<H1 class=”topic_type1″>’+document.title + ‘</H1>’)

In this example we are using the heading one class to apply the format, which is controlled in our .css file in flare. This can make use of colours and icons to make it clear what sort of information is being provided.

The beauty of this approach is that should you need to change the criteria or the look and feel of each topic, you simply update your one .js file.

May 3, 2006

What is: Vista Office Help

Filed under: Information Types,Technology,Vista,What is — AndyR @ 12:45 pm

If you haven’t this across it yet, it is well worth a look. Jenson Harrison is the Lead Program Manager on Microsoft Office. It gives the inside line on how the new UI will work in Vista.

For help authors this enables us to get a headstart with our thinking on how we will deliver help.

Posts of note for help are:

April 3, 2006

What is: MAML

Filed under: Future-proofing,Information Types,Technology,Vista,What is — AndyR @ 12:42 pm

MAML is part of a new approach to help in Windows Vista. This approach is both more integrated with the software and more focused on user tasks. MAML provides a structre in which you can write user assistance information, which can then be presented to the user in a variety of locations.

An example of help using this schema (http://schemas.microsoft.com/maml/dev/2004/10) can be found on the Microsoft Office Online Assistance. Additionally, if the user chooses to get the latest online content, that content is downloaded to the local machine as MAML and transformed at runtime into HTML for display, just as the local content is.

MAML Topic Types
The following types of topic are currently in use in the new MAML based Office Online pages:
MAML_training.gif Training: to learn more about using programs, focus on features or activity areas and allow to suggest best practices. Courses are self-paced, and include graphics, animation, audio, and practice sessions for hands-on experience. They have an inherent browse sequence
MAML_article.gif Article: up-to-date information in the form of how-to, and tips information.
MAML_topic.gif Topics :conceptual information about functionality and theory behind features.
MAML_disucssion.gif Discussion: online Community where you can interact with fellow users, get your questions answered, share ideas, and learn more about products and technologies that interest you.

Reference
–Vista Help Technical Overview

What is: Assistance Platform

Filed under: Future-proofing,Information Types,Technology,Vista,What is — AndyR @ 7:00 am

MAML.gifAssistance Platform (AP) is part of a new approach to help in Windows Vista. This approach is both more integrated with the software and more focused on user tasks. AP is the technology used to deliver Help for windows vista. It takes the MAML content and presents it to the user in an appropriate location.

Rather than present user assistance information as one help file with a large Table Of Contents, it can now appear in the following locations:

-Directly in User Experience
  – Embeded Help 
  – Super Tooltips 
  – Ribbon 
  – Help pannels
-In application Context
  – Help window
-No Context
  – Help Centre

AP Wokrflow (Programming Windows Help PDC03)

  1. Well-designed app UI
  2. Assistance directly in app UI
  3. Help Pane and Help Center
  4. User community
  5. Your product support center

February 17, 2006

Best Practice: Topic Types

Filed under: Best Practice,Future-proofing,Information Types — AndyR @ 1:27 pm

Helps often deal with a plethora of different information. Not only is the information required by different readers in different contexts, it is also collected from a range of sources of varying quality and style.

From our conversations with developers we glean those handy shortcuts and tricks that they spend extra hours programming. They provide lists of hotkeys and data types for us to compile. They provide lists of form names and database tables.

We consult the scope documents and find a raft of sales reasoning for implementing the software. They tell us about the numerous users clamouring for this new feature. We read explanations of business processes, and the key words that the market uses for this functionality.

We consult the product manager and note key executive points essential for the user to understand the function. They wax lyrical of the ways this will save the user time, and therefore general more sales.

The stack of information for our project stacks pretty high. But in there are the gems that trun a good help into a great one. The key to unlocking this is in the way we organise the information. With so much to go on the tendancy is to start pumping it into our help authoring tool, but this can result in a variety of topics covering the software from several angles, each one overlapping the next to a greater or lesser extend.

We need to get organised. And for me the key tool in this has not been a new super help technology or authoring tool, it has been some premeditated strategising. I needed to be able to categorise the information I had so that I could start to know what went where, and avoid repitition. One way this can be achieved is by defining a strict set of topics.

Definition: Your topic types need to be strict enough so that you know what information should be included, but also flexible enough to cope with the inevitable oddity bits of information. You should define a rough template for each type of topic that outlines the sturcture and content that will usually be included.

Relationship: There should be a clear progression from one topic to another. It can help to build up a model of how a user my read and cross reference each of your topic types. Ensure that you don’t have topics that are essentially stranded with low visibility.

Appearance: Once you have your ideal topic type set, you need to do some work to ensure that the user can tell what type of topic they are reading. It can be useful to get a graphic designer involved at this stage if possible. You should be providing visual clues such as colour, iconography and structure that signal to the user what sort of information they can expect to find.

If you are able to do this effectively, this means that you not only are able to produce streamlined helps that are easier to navigate, read and maintain, but you are also ready to move to new formats (such as DITA or MAML) that expect this sort of information definition.

You can extend your handling of information, by considering how you title your topics. A comprehensive and consistent approach to topic titles, essentially pick-up on ideas similar to that of tagging made popular by the recent success of del.ici.ous.

February 14, 2006

Best Practices: Delicious Topic Name

Filed under: Best Practice,Information Types,Navigation — AndyR @ 1:06 pm

DeliciousTopic titles, you can’t live with them, you can’t live without them. But these little text strings sitting incongruously at the top of our topics have an untapped power to enable users greater access to the information contained within.It wasn’t until I was recently using Del.icio.us that I saw how key topic titles are to accessing information in helps. If you haven’t come across it yet, “Del.icio.us is a social bookmarks manager. It allows you to easily add sites you like to your personal collection of links, to categorize those sites with keywords.” It has had a meteoric rise to fame the past year.

This popularity is due to the power of this categorisation. The keywords associated with each bookmark enable incredibly powerful and flexible searching. This is something we can learn from for our helps. When users are searching for topics they do a keyword search and are presented with a list of topic titles. We have the oportunity of making these titles much richer by considering them as a series of “tags” that categorise the topic content, similarly to the bookmark “tags” in Del.icio.us.By employing a strict naming convention to your topic titles, you can signpost key information to your users. To achieve this, you need to do some work on the type of information that you are going to include in your help. For example, you may include topics about Dialogs, Procedures and Concepts. Here are you first three “tags”.

Next consider each of these categories of topics and consider the types of information provided in each. For example, your procedure topics may contain information about creating New records, Editing, Deleting and Copying existings record. Htere are you next subset of “tags”.

Once you have completed this for all the types of topics in your help you will have a list of tags from which to compile topic headings for each topic.

The results is a help with strictly named topics, always using the same keywords (or “tag”) to identify the information it contains.

Although this may seem trivial (and not a million miles from what we would naturally do anyway), the application from an absolutely strict set of titles means that the user always has the same textual clues when searching for information.

Additionally, this approach prepares us for distinct topic categorisation as required by DITA and MAML. We can also make use of these categories to style topics differently for each type of information, providing further visual clues about the topic.

Finally, this also enables us to use topic titles if we want to generate a set of see also topics using some scripting technology.

 

Blog at WordPress.com.