Tech Write Tips

January 11, 2007

Best Practice: Search and Replace

Filed under: Best Practice — AndyR @ 1:15 pm

mag.gifOnce you have your topics in a strict XHTML form, you are able to work with them in more detail. You can use the ‘strict-ness’ to ensure that the content is more consistent.
Although this primarily enables you to use XSL transforms to check and move the content into any required format, it is often overlooked that the clean content is primed for a plethora of searches to ensure your standards are being applied.

A tool such as textpad provides enables you to performing the following S&Rs:

  • Terminology: Simple search for terms that are not used by your house style.
  • Formatting: Search that particular terms have the appropriate xhtml formatting.
  • Linking: Search to ensure all instances of particular types of elements are linked. For example, all instances of ‘dialogs’ and ‘tabs’ link to the appropriate topic.

Care should be taken when doing a global S&R as there is as much potential for creating global problems as there is for fixing them.

Textpad enables you to use regular expressions to refine these searches. Regular expressions 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.

August 18, 2006

Best Practice: Screen Estate

Filed under: Best Practice,Tip — AndyR @ 12:55 pm

As mentioned in the Jenson Blog recently, screen real-estate is at an all time premium. When you see how much time and effort is spent ensuring software doesn’t needlessly waste screen real-estate, it makes you realise the responsibility we have as authors to use the help window wisely.

Alot of benefit can be gained by considering ways in which we can make best use of the space.

  • Provide navigation within each topic so the users doesn’t have to open the TOC to move around the help.
    • Breadcrumb trail
    • Cross Topic links
    • See Also links
  • Open the HTMLHelp with TOC minimised
  • Desgin topics to fit in smaller portion of screen.
    • Screen shots width is critical
    • Tables used for content or layout should fit width
  • Avoid scroll bars appearing by fitting content to one window
    • Turn off test on the HTMLHelp toolbar buttons
    • Provide help topic in a pane contained in the application.
    • Turn off keep help on top.

July 20, 2006

Best Pratice: Flare 4 – High Definition PDF Part 2

Filed under: Best Practice,Madcap Flare,Technology — AndyR @ 7:00 am

Having introduced the concept of high definition PDF’s output straight from Flare’s source files with minimal post-production, we can now start to dig into the technologies that are used to produce it.


The XSL style sheet produces the following sections of XML-FO :

  • Page Layout Definitions
    • Page Sizes and Layout
    • Branded Headers and Footers
    • Odd Even Pages
  • Branded Title Pages
  • It firstly calls the Flare TOC file, using the @Title element, to create the bookmarks for the pdf.
  • It secondly calls the Flare TOC file, using the @Title element to create a structure for the document.
    • Table of Contents
    • Chapters
    • Main Headings
  • It thirdly calls the Flare TOC file, using the @Link element to locate each topic in turn.
    • Each topic is then added to the above structure.
  • Branded Back Pages 

This is all wrapped up as one big XML-FO file.

The XML-FO file is then passed into the Apache FOP engine which outputs the PDF document.

In the next part we’ll look at some of the key issues to solve with this process and the code you can use to overcome them.

July 19, 2006

Best Pratice: Flare 4 – High Definition PDF Part 1

Filed under: Best Practice,Madcap Flare,Technology — AndyR @ 6:59 am

prime.jpgIn this article we take things up a notch. This enters the realm of the real tech tip. If you want your authoring tool to do everything for you and don’t want to delve into CSS, XML and XSL then maybe you should move onto the next post.

Those still reading, lets roll our sleves up and have a look under the hood. The aim of todays article to to produce a high quality pdf document that has at least the following features:

  • Front Matter
    • Graphical Front and Back page
    • Table of Contents for the book
  • Separate Chapters
    • Mini Table of Contents for each Chapter
    • Chapter name in the header
    • Clickable links from Table of Contents to relevant section
    • Marginalia (notes, references, notifiers)
  • Full Bookmark tree.
  • Odd/Even Pages
  • Odd/Even Headers and Footers

Bit of a tall order, maybe. But with the following technology you can achieve this from your Flare source files. Once setup you can then generate it at the click of a button.

The technology we will be using are XML, XSL, XPATH and XML-FO. In part 2 we will detail the steps in this process.

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.

July 6, 2006

Best Pratice: Flare 1 – Reporting

Filed under: Best Practice,Madcap Flare,Tool — AndyR @ 12:32 pm

The first of our mini-series of tips for Flare, here we consider how to leverage that old RoboHelp licence to squeeze some extra information out on your Flare HTMLHelps. 

It is advisable to ensure the following checks towards the end of a help project:

  1. Technical correctness check by Designer
  2. Help integrity checks by Technical Author
  3. Grammatical check by Proof Reader
  4. Accessibility check by the Tester

The second stage here requires a high degree of reporting information. To aid us with this we need to leverage functionality in RoboHelp until the reporting in Flare is updated. The following process enables you to gain a whole host of additional information about your Flare HTMLHelp project. Perhaps you CAN have your cake and eat it:

  1. Towards the end of your help project in flare.
  2. Generate output and save a log of the issue as a report.
  3. Run through this report, correcting the errors.
  4. Generate output again.
  5. Take a copy of the temporary output from:
    1. PROJECT\Output\USER\Temporary\Microsoft HTML Help\Content.
  6. Open the _Temp.hhp in your legacy copy of RoboHelp.
  7. Work through the topics in the RoboHelp Broken links section to fix links back in flare.
  8. Select the TOC in Robohelp, check through the list for topics not included in the TOC. Add these items into the TOC back in Flare as appropriate.
  9. Select Tools | Report in RoboHelp and use any additional reports to check content.

July 3, 2006

Screen Portrait Mini’s

Filed under: Best Practice,Technology — AndyR @ 5:00 pm

Further to our discussions about screen portraits (our cell shaded alternative to screen shots) Another case for the importance of screen portraits is the fact that Vista Super Tooltips enable you to include images in the popup pane.

These images can provide graphical clues about the use of a function, or provide a preview of the dialog that will appear when an operation is selected.

These inevitably nudge us back towards providing more screen shots, and therefore greatly increase the maintenance load on the online help (or should we now say User Assistance). If a screen portion or layout is adjusted you suddely have a stack of updating to do in the help files.

Screen portraits enable you to include these graphical enhancements to toolstips and topics, but minimise the maintenance cost. You should not need to update the images unless a screen or function has been completely revised. If this is the case you would likely want to revisit the help in any case.

March 28, 2006

Best Practice: Screen Portraits

Filed under: Best Practice,HTMLHelp — AndyR @ 12:37 pm

It seems that the post about screen portrait generated quite a bit of interest. So I thought I would provide some more "How to" details.

Stage 1portrait1.gif

  1. Bring the screen shot into your paint package. I use PaintShop Pro
  2. Ensure that the screen is configured in such a way that all the general features are available, so it depicts the required functionality.
  3. Also Ensure that it is good aspect, so the resulting portrait will fit your help topic. This can be adjust at the end but not as easily.

Stage 2portrait2.gif

  1. Provided your paint package supports layers, and most of the do, start adding rectangles to mask over the key parts of the screen.
  2. A feature in PaintShop Pro is to tmake a layer semi-transparent, as you can see, I make my rectangles transparent so I can still see the screen shot behind them. This makes for easier laying out.

Stage 3portrait3.gif

  1. Start to add in the key details of the dialog, ensure that anything that is referenced in the help is included.
  2. What you are looking at doing is replicating the visual signature of the image.
  3. In the same way that we recognise words by their overall shape rather than each letter, the same is true with how we recognise software screens.
  4. For example you could probably recognise a Font selector dialog from across the room.
  5. You can probably make your portraits more styalised than you will first imagine. Practice makes perfect.

Stage 4portrait4.gif

  1. Turn off the original background image in the paint package so you can only see the portrait.
  2. You can add some bells and whistles like rounding the containing area to match the rounding in windows.
  3. There you have it, your finished portrait.
  4. I estimate you can knock these out in about 3-4 minutes once you have a sample layout completed.

Next post about this we will focus in more detail about the colours, positioning and visual clues to make your portraits sing.

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.

Next Page »

Blog at