Skip Headers
JavaTest Harness Architect's Guide,
JavaTest Harness 4.5 for the Java Platform
  Go To Table Of Contents
Go To Index


C What Technical Writers Should Know About Configuration Interviews

Technical writers can greatly contribute to the quality of a JavaTest configuration interview — think of the text in a configuration interview as being equivalent to an application's user interface; the better the text, the easier the test suite is to run. There are two areas where a writer's contribution is extremely important:

Question Text

Interview questions should be written as concisely, consistently, and clearly as possible. Any amplification, clarification, or examples should be included in the More Info pane.

Not all questions are really questions; some "questions" are written as statements that instruct the user to specify, choose, or select an item of information.

To see an example interview, run the JavaTest tutorial in Chapter 2. The tutorial uses the Demo TCK that is part of the JavaTest Architect's release.

Question text is kept in a Java properties file associated with the interview class files; you get the path to the properties file from the interview developer. Every interview question is identified by a unique key. The key is based on a name assigned by the developer and should uniquely identify the question with the interview. Keys are of the form:


The following is a snippet from the Demo TCK interview properties file:

title=Demo Interview Configuration Editor
DemoTCKParameters.cmdType.smry=How to Run Tests
using a JavaTest Agent?computer (using a separate JVM), or to run them on another computer DemoTCKParameters.cmdType.text=Do you wish to run the tests on this 
DemoTCKParameters.cmdType.agent=Using a JavaTest Agent
DemoTCKParameters.cmdType.otherVM=On this computer Configuration Values...
local settings of some parameters required by some of the following questions determine the 
identify the configuration you are creating here.DemoTCKParameters.desc.text=Please provide a short description to 

The file contains the following types of elements:

More Info

As a technical writer, you can really add value to a test suite in the configuration interview More Info pane.

Figure C-1 The JavaTest Configuration Editor: Question and More Info Panes

Description of Figure C-1 follows
Description of "Figure C-1 The JavaTest Configuration Editor: Question and More Info Panes"

The text displayed in the More Info pane is formatted using HTML 3.2 tags and provides a reasonably rich environment for formatting text. Although the text can be created using a WYSIWYG HTML editor, most More Info text is short and simple and is easy to create manually using a text editor.

Typically, the developer who creates the configuration interview creates the basic More Info system, seeding it with empty HTML files that you can fill in with text.

Experience has shown that it is best to create one HTML More Info file per interview question. It is also a good idea to name the More Info HTML files after the property names of the questions they describe. For example, in the snippet in the previous section, you can see that the DemoTCKParameters interview contains a question named cmdType — you should expect to see a corresponding More Info file named cmdType.html.

Formatting Styles

The following tips can be helpful when formatting your More Info topics:

Your More Info topics should link to the style sheet included in this package named moreInfo.css.

  • Use only HTML 3.2 tags because of limitations in the HTML viewer

  • Section 508 accessibility rules may apply

  • Do not create hypertext links to other More Info topics or other external documents

  • Do not add any <p> tags between the <body> tag and the initial paragraph

  • Use the <i> tag for variables in command lines — use the <em> tag for emphasis

  • All file names and code examples should be formatted in the fixed-width font using the <code> or <pre> tags

  • The style sheet (moreInfo.css) contains a "tight" class that you can use with <li> tags for lists in which you want less vertical space between list items. For example:

  • <li class="tight">This item is closer to the previous list item</li>

  • Indent path names and code examples using the <p class="code"> tag. The code class indents the lines 8 pixels and has no top margin. For example, the following HTML:

    <p class="code">
    <p class="code">

    Produces the following output:


Usage and Conventions

The following list describes some conventions that have proven useful for writing More Info text:

  • Use the present tense when possible. For example, instead of:

    "The following questions will gather..."


    "The following questions gather..."

  • When reasonable, provide examples in both Unix and Microsoft Windows format