Tech Write Tips

January 11, 2007

What Is (Are): Regular Expressions

Filed under: Madcap Flare,Technology,Tip,Tool,What is — AndyR @ 1:15 pm

regexp.gifRegular expressions are used to perform complex searches in software such as Flare and Textpad. They enable you to identify phrases that are not (“a^b”) followed by particular characters. They enable you identify phrases that can contain optional (“a|b”) sections.

Some examples of these phrases, used in practice by technical authors are as follows:

  • “[^=|(]”[^ |>|?|/|)]” – Find quotes not in HTML attributes. We only use single quotes. This expression locates any quotes not related to an HTML attribute, i.e. in the body of the topic text.
    • Avoids ‘” ‘ (end of attribute mid tag)
    • Avoids ‘”/>’ (end of attribute end tag)
    • Avoids ‘=”‘ (start of arrtibute)
    • Avoids ‘”?’ (header doctype)
    • Avoids ‘(“‘ (filename in quotes)
  • “[^,]” – Find the phrase without a preceeding comma. This is useful if you always use phrases of the form “To achieve XXX, perform the following”. It identifes any places you have missed the “,”.
  • “[^(his)|(he)|(current)] dialog[^<|s| |)]” – This assumes you provide links from procedural topics to screen topics. For example from “Student Dialog”. It works by identifying all occurences of “dialog” that are not proceeded with the end of the link “</a>”.
    • Avoids “This dialog”
    • Avoids “The dialog”
    • Avoids “Current dialog”
    • Avoids “dialogs”
    • Avoids “dialog “
    • Avoids “dialog)”
    • Finds “dialogs” not followed by “</a>”
  • “tab[^<|s| |e|a|l|]” – This assumes you provide links from procedural topics to screen topics. For example from “Student tab”. It works by identifying all occurences of “tab” that are not proceeded with the end of the link “</a>”.
    • Avoids “tabs”
    • Avoids “tab “
    • Avoids “tabe”
    • Avoids “taba”
    • Avoids “tabl” (table)
  • “[^(and)|(This)|(</a>)] Tab[^h|<|\.|”|l|e|s|a]” – We always have the control type (dialog, tab etc) in lowercase, this expression identifies any cases where “Tab” is uppercase and not the start of a sentance. It also rules out occurences inside “Table” etc.
  • “<img.*/> “– Images with spaces afterwards. We insert spaces after images via a css style, so need to ensure that the images don’t have “hard spaces” after them.
  • “[^ |>]<a” – Find links without whitespace before them.
  • “[^ |>|(]<b>” – Find bold text without whitespace after.
  • “<a.[^(href)]” – links with no href tag.
  • “href=””” – links with empty hrefs.

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.

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

What is: XSL

Filed under: Technology,What is — AndyR @ 1:35 pm

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

February 17, 2006

What is: CSS

Filed under: Technology,Tool,What is — AndyR @ 1:26 pm

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

Filed under: Technology,What is — AndyR @ 1:25 pm

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.

Blog at WordPress.com.