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:
<Button>
  <Button.Background>
    <SolidColorBrush Color=”Blue”/>
  </Button.Background>
  <Button.Foreground>
    <SolidColorBrush Color=”Red”/>
  </Button.Foreground>
  This is a button
</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.

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.

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

What is: XPATH

Filed under: Future-proofing,Technology — AndyR @ 1:38 pm

XPath is a way of pulling out particular data from an XML document. It is used by XSL to determine what should be output in your documents. It is essentially a systematic way of defining an address of each piece of data.

For example, if you have a nested set of tags:
<person>
 <age>46</age>
 <surname>Adams</surname>
 <age>28</age>
 <surname>Jones</surname>
</person>

You can pull out just the surnames by the XPATH expression "person/surname". This returns all the surnames inside the person tag, in our example this would return "AdamsJones".

As well as these addresses, XPath lets you use a raft of functions to work with the data returned from your specified address. For example you can use the UpperCase function to change the case of the output. upper-case(person/surname) returns ADAMSJONES.

For the technical author who wants to dabble at this level, XPath combined with XSL enables you to generate datasheets from raw xml data. If your help content is in an XML compliant form (such as XHTML), these technologies also enable you to transform it to a variety of other formats and medium, such as web or pdf.

February 21, 2006

Best Practice: Screen Shots vs Screen Portraits

Filed under: Best Practice,Future-proofing,Technology — AndyR @ 1:04 pm

screenshot2.gifWith the increasing tendancy towards re-using help content in a varierty of different contexts, both within the help itself and in different places in the application, we are less sure about how much space we have to display the help content. In the richer interface of windows Vista Screen real-estate is more valuable than ever.

This means that there is less space for screen shot graphics of the interfaces we are addressing in our helps. Where previously we could be sure of the positioning and visibility of our screen shots, this is less and less the case.

screenportrait2.gifThe solution? Copy Microsoft. You may not have noticed the movement away from screen shots in their help pages, but there appears to be a trend away from screen shots towards what we are calling screen portraits.

A screen portrait is a drawn representation of the application window. This enables it to be simplified and small. You currently see them appearing largely in their About topics.

It may seem like extra work to produce bespoke screen representations from scratch. But we suggest that this time is a good investment for the following reaons:

  • Readability: Screen portraits are designed to be recognisable at small sizes, whereas screen shots loose readability when reduced in size.
  • Size: Screen portraits are able to consume less screen real-estate, whereas screen shots demand a large portion of the help pane.
  • Annotations: Screen portraits can have annotations designed in, whereas screen shots have to have annotations super imposed over them which can look clumsey and confusing.
  • Selectivity: The process of producing your screen portraits means that you can assess which graphics are actually needed, and which don’t add anything to the help text.
  • Maintainability: Small adjustments to software don’t result in new screen portraits, whereas screen shots would have needed to be updated.

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

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 WordPress.com.