Tech Write Tips

October 6, 2006

What is: XAML (authoring’s best kept secret)

Filed under: Future-proofing,Technology,Tip,Vista,What is — AndyR @ 12:02 pm

microsoft-expression.gifXAML is an XML file that defines user interfaces. It not only defines the frames, buttons, fields but also introduces any other visual effect that the interface may require. In a similar way to Flash interfaces, XAML provides a rich user experience with a variety of graphical effects.

XAML, a markup language to declaratively represent user interface for Windows applications, improving the richness of the tools with which developers and designers can compose and repurpose UI.

For example, you could define a button as follows:
    <SolidColorBrush Color=”Blue”/>
    <SolidColorBrush Color=”Red”/>
  This is a button

So what! How does this help the technical author? Here we find one of the best kept secrets of this new technology. Whilst its benefits for programmers and designers is often highlighted:

“One great benefit of XAML is that it helps to separate design and development, which actually helps to improve collaboration and efficiency between designers and software developers.”

What is less publicised is how this opens up the development process to other players, such as the technical author. Not only does this help close the great divide between authors and devlopers, it also starts to provide a route to achieving the sort of user guidance offered by Assistance Platform.

Firstly, it becomes a possibility for the technical author to become the owner of all the text in the appication. The user interface text in the XAML files can easily be updated with little programming knowledge.

Sceondly, it also become possible to generate templates for dialog help, as the XAML can be transformed with an XSL to produce a XHTML page that lists all the fields and includes notes as the starting point of the help project.

Thirdly, the XAML itself can also be checked from a consistency perspective. An XSL file can run through the file checking it aganist the companies interface standards. Again this helps the technical author flag up any issues with the user interface.

We find that this helps, authors move towards providing more wide spread User Assistance than simple help files. Aspects of Vista, such as super tooltips, require much more integration between the help content and the application. XAML provides a means for us, technical authors, to play our part to achieve this.

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 ( 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.

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 14, 2006

The Great Divide

Filed under: Future-proofing,Vista — AndyR @ 1:14 pm

SuperTooltip.gifWhat was once a great divide between the help content and the software, is fast becoming harder to delineate. Where does the software stop and the help start.

The drivers of new technology are unavoidably software focused, this is where the most investment and thought is invested. This has histroically been done in isolation of help, which have largely come into existence off the back of website technologies.However, more recently we are seeing increasing embracing of user assistance as part of the software itself.

The divide between the software and the help is becoming significantly blured.Windows Vista’s ribbon bar and super tooltips are two examples where the advice on using functionality and the buttons that actually achieve it are becoming one.

The ribbon presents both textual and graphical clues to enable the user to understand how to use it.

Super tooltips provide effectivley a mini help topic within the application (perhaps foreshadowed by WebHelp popups).

This development, far from threatening the position of the Technical Author, presents an opportunity that has been long awaited in the industry. The communication skills of the author can be utilised not only in the separate (and sometimes strange land of) online help, but can be brought to bear in the software itself.We are no longer simply bridging the gap between the software and the user. Rather we are closing the gap to enable the software and the user to work more closley.

It is essential to our industry that we prepare and capitalise on this opportunity. Our single sourcing needs to be ready to produce content for a wider variety of media (embeded help panes, super tooltips, ribbon content). Our topic categories need to complement the types of popups required in the software (particularly super tooltips). Our context linking needs to complement the help within the software with additional targeted information.Finally, this is where the rubber is going to hit the road for incosistencies in language between the help and the software. We need to be ready to provide standards for naming and describing the pallete of tools and dialogs employed to deliver functionality. Then, devlopers and tech authors have the chance of addressing the user with the same words, with consistent tone, and without needlessly repeating themselves.

Blog at