What is: XPATH

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.

Best Practice: Screen Shots vs Screen Portraits

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

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

What is: XSL

Having discussed the difference between HTML and XML, and established the benefit of XHTML content, we can now look at one of the benefits of this strict clean XHTML format, namely XSL.

XSL stands for Extensible Stylesheet Language. As it’s name suggest it is essentially a simplpe programming language. HTML documents can only output content in the order it appears in the file. XSL enables you to disaplay XML documents in more complex ways.

It enables you to control which parts of the file are output, and where (and how often) it appears. You can do things like output a heading for each Surname in your XML, or start a new row of a table for each persons address. You could output the same personal details from your XML in three or four different orders. Your XML document may contain some tags where someone’s name appears just once, but also contains four addresses for that person. XSL enables you to pull out the name each time you output the address.

XSL does enable you to output content and style tags in the same file. Taking an XML file and using XSL to output structured content including formatting:

• XML – Content
• XSL – Structuring and Look and Feel of Output

In my experience it is better to use it to output just content and keep the look and feel in a separate CSS which is referenced in your output. This then retains the separation bewteen content and style that we introduced with CSS:

• XML – Content
• XSL – Structuring of Output
• CSS – Look and Feel of Output

Best Practice: Topic Types

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.

What is: CSS

Originally HTML webpages combined both content and appearance. For example you had to embed a <Font/> tag in amoungst your content to specify a font. CSS enables you to control the look and feel of webpages without interfering with the content. Becuase of it’s exclusively appearance focus it uses a different syntax to that originally used in HTML.

The advantage of this separation is that you read the appearance syntax alot easier as it is not mixed up with the content. The same is true of the content, being free of appearance tags. You can also use one CSS to control the appearance of multiple wepages, which makes it easier if you need to alter their appearance.

When starting to work with CSS it is essential to work with a tool that can help you with the syntax. Topstyle Lite is a free tool that enables you to pick the styles from a list rather than type them in. Flare is a more comprehensive tool that integrates CSS not only with a WYSIWYG HTML editor, but also manages all other aspects of producing online help.

As you familiarise yourself with CSS, which for me has been a good 5 year journey, you will gain an increasing understanding of how best to use it. The learning curev usually develops along the following: Syntax Familiarisation; Relating Styles to Particular HTML Tags; Higherarchey of Formatting; Conditional Styles.

What is: XML

XML is essentially a name for any tag based data that adheres to specific rules about how the tags are used.

Generally, HTML doesn’t mind if you don’t always close tags and don’t have quotes around attributes, it cuts you some slack. This means it is not an example of XML. It gets away with this because most browser are tolerant of a variety of HTML tagging styles.

XHTML is HTML where all the rules are adhered to. Its good because it means your pages are always exactly defeined. This means that if you need to transform the page in the future you won’t run into problems with the fuzzyness of your tagging. It also means that you can draw on a raft of tools and technologies that have built up around XML, such as CSS, XSL and XPATH.

I also recoment the www.w3schools.com site. Its excellent for first principles and references.

HTMLHelp Tab Tops

I recently came across this account of why the tabs on HTMLHelp files are sometimes displayed with the old style tab tops.

The bottom line is as long as the host application has registered a manifest, the help will appear themed. If it doesn’t (like the hh.exe viewer) then it appears with the old tabs tops.
You can fix this by creating a manifest file in the same folder as the .exe with the name [Executable Name].manifest. For example “HH.EXE.manifest”. Then add the following content:
<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<assembly xmlns=”urn:schemas-microsoft-com:asm.v1″ manifestVersion=”1.0″>
<assemblyIdentity name=”MyHH.exe.Manifestfix” processorArchitecture=”x86″ version=”1.0.0.0″ type=”win32″/>
<description>MyHH.exe.Manifestfix</description>
<dependency>
    <dependentAssembly>
        <assemblyIdentity type=”win32″ name=”Microsoft.Windows.Common-Controls” version=”6.0.0.0″ processorArchitecture=”x86″ publicKeyToken=”6595b64144ccf1df” language=”*”/>
    </dependentAssembly>
</dependency>
</assembly>

Best Practices: Write a Dictionary

It has been said that a dictionary is a:

“malevolent literary device for cramping the growth of a language and making it hard and inelastic. This dictionary, however, is a most useful work.”

This is the crux of the matter. The dictionaries imposed on us can be seen as cramping style and limiting creativty. However, if we use and own our dictionaires, they become tools that frame and enable our highest works of communication. Ownership and use are key, and go hand in hand. This is the basis of today’s best pratice suggestion. Start your own dictionary, make it particular to your work, then get in the habit of using it. I have found the following features useful in our in-house dictionary.

• Build on existing style manual. We use Microsoft Manual of Style for Technical Publications, it’s not perfect but it gives us a starting point.
• In your dictionary document it is useful to be able to sort in a variety of ways. We find it particularly useful to order entries by their created date.
• Ideally your dictionary should be searchable, we do this with some xsl filtering, but as long as your is electroinc is should be pretty straight forward to search.
• Finally, ensure your dictionary is freely and easily accessible to those who need it.

You should record your dictionary in the medium that best suites your needs. We use an xml file which is then transformed for viewing. This enables it to be viewable in  avariety of formats and quickly ordered or searched as required.

XML File:
<Entry>
 <Date></Date> – Date the netry was added to enable you to highlight new entries.
 <Update></Update> – Updated date to enable you to highlight updates.
 <Category></Category> – Grouping of the type of entry, is it general grammar, procedural or formatting.
 <Item></Item> – Unique reference for the item, usually the word or phrase in question
 <rule></rule> – A description of how the item should be used.
 <Correct></Correct> – An example of how the item should be used in practice.
 <Incorrect></Incorrect> – An example of how the item should not be used in practice.
</Entry>

XSL File:
<xsl:for-each select=”//Entry”>
 <xsl:sort select=”Update” order=”descending”/>
 <B><xsl:value-of select=”Item”/></B> <xsl:value-of select=”Category”/>
 <P><xsl:value-of select=”rule”/></P>
 <UL>
  <xsl:for-each select=”Correct”>
   <LI>Correct: <xsl:value-of select=”../Correct”/> </LI>
  </xsl:for-each>
  <xsl:for-each select=”Incorrect”>
   <LI>Correct: <xsl:value-of select=”../Incorrect”/> </LI>
  </xsl:for-each>
 </UL>
 <P><xsl:value-of select=”Date”/> <xsl:value-of select=”Update”/></P>
</xsl:for-each>

The Great Divide

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

Best Practices: Delicious Topic Name

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