HyperWord Services

 

Home

Resources

Services

Contact Info

About Hyper/Word

 

Copyright © 2003 Hyper/Word Services

 

Project Control Documents

 

If you're new to online help or documentation projects, you're probably discovering that there are many things to keep track of.

  • The development steps.
  • Any required order in which to perform those steps. Any suggested order.
  • Documenting a project to create a reference that will help the next developer (who may be you), get up to speed without having to relearn the project from scratch?

Hyper/Word Services offers a project task list and a project spec template based on 18 years of online development experience, including 12 using, training, and consulting on RoboHelp.

For more information, click the appropriate link in the table below.

Project Task List Project Spec Template
Overview Overview
The Table of Contents The Table of Contents
Sample Sections Sample Sections
Format, Usage Rights, and Price Format, Usage Rights, and Price

Project Task List

Overview

This document describes the tasks in the four main phases of any project:

  • Pre-start — How to look for and deal with style problems in legacy documents to be imported into the project, template definition, topic categorization for build tags, and more...
  • Development — Folder creation, style sheets, topic creation, links, tabs, and more...
  • Final build — Compiler errors, unapplied style sheets, and more...
  • Wrap-up — Spec updates and archiving.

Each task description explains when to perform the task, any dependencies to consider, the steps, and any notes, tips, tricks, or warnings. The tasks are oriented toward RoboHelp HTML, but can be used with any other help authoring tool.

The Table of Contents

Introduction

Pre-Start

  Review the Project Information
Review the project spec to understand the project's rationale and structure
    Verify the desired output format
    Go over any feedback from the previous release
    Review any compiler errors and decide whether to fix them
  Check For and Correct Style Problems in Material To Be Imported
    Review any Word, HTML, or Framemaker files to be imported into the project
  Verify Other Project and RoboHelp HTML Settings
    Verify whether this is a context—sensitive help project
    Verify whether you need to be doing single—sourcing
    Determine whether you need different topics or topic content in different outputs if you'll be single sourcing
    Determine whether you want to apply standard content to your topics
    Define a standard "Come back here" marker
    Decide whether to create Related Topic lists
    Verify that the "Use Underscores In File Names" feature is turned on

During the Project

  Define the Structure and the Display Settings
Define the topic folders and subfolders for the project
    Create any necessary topic templates
    Create the style sheet(s) for the project
    Help your subject matter experts (SMEs) use styles correctly
  Working With Topics
    Create the new topics
    Import any existing topics
    Changing a topic title
    Insert any graphics into the topics
    Replace the graphic in a multi—hotspot graphic
    Insert any multimedia into the topics
    Correct potential problems with the Flash player
    Create the glossary
  Create Navigation Mechanisms
    Create Links
    Create the Contents tab
    Create the Index tab
    A confusing Smart Index Wizard feature
    Create or modify the browse sequences
  Define or Modify the Interface
    Set the Help window size
    Specify the window title bar
    Modify the tabs pane width in the Microsoft HTML Help format
    Create or modify a skin (for WebHelp or WebHelp Enterprise projects)
    Create and apply the skin
    To modify an existing skin
    To create a button
    The "Powered By RoboHelp" icon
    Create bookmarks
    Create framesets
    Other tasks and suggestions

Final Steps

  The Tasks
Check for unfinished material in topics
    Check for unapplied style sheets
    Other

Closing and Archiving

  The Tasks

Sample Sections

Determine whether you need different topics or topic content in different outputs if you'll be single sourcing

When to: As soon as possible to start planning the different output mixes and the required build tags.

Note: You can actually do this at any time during the project. However, doing so at the beginning makes it easier to visualize and define the overall structure that you're trying to create before you get tangled up in the details of the project.

Dependencies:

Definitions of the different outputs and the topics or topic content to include in or exclude from each. The definitions usually come from engineering or marketing as they define the different user groups to support — e.g. "lite" version buyers vs. full version buyers, novice vs. intermediate vs. advanced users, regular users vs. system administrators, etc.

Understanding the Boolean operators that control the output. For example, if you classify some topics as Novice, some as Intermediate, and some as both, under—standing how the output results differ if you select Novice AND Intermediate topics vs. Novice OR Intermediate topics.

  • If you'll need different topics or topic content in different output, define the categories of topics or topic content and give each category a short (one— or two—word) reference name.
  • Create the "build tags" — RoboHelp HTML's implementation of your categories. (Right—click on the Conditional Build Tags folder on the Project tab, select New Conditional Build Tag, type the tag name, and select the desired tag color.)

Verify that the "Use Underscores In File Names" feature is turned on

When to: Any time before actual development begins.

Dependencies: None.

  • If a topic file name or folder name contains spaces, you may get a seemingly inexplicable "Out-of-memory" error during compilation. This is caused by spaces in the name. The "Use Underscores In File Names" feature eliminates this problem 99% of the time by automatically replacing spaces in file or folder names with underscores. (The "Convert Spaces to Underscores" feature, described later, eliminates the remaining 1% risk of the problem.)
  • The "Use Underscores In File Names" feature is turned on by default but it's a good idea to verify this, especially if you inherit someone else's PC. To verify:
    1. Select Tools/Options.
    2. Click the General tab.
    3. Make sure the Use Underscores In Files Names option is selected.
    4. Click OK.

Format, Usage Rights, Price

Format — The task list is a Word document which you'll receive online.

Usage rights — Unlimited usage rights within your documentation group, or within your company if there's only one documentation group.

Price — US $30, by check or money order. (Mass. residents please add 5% sales tax.)

Project Spec Template

Overview

Online projects typically lack any documentation. Developers who have to maintain and update a project typically have no information about the project's settings or even why it was designed the way it was. The result? Wasted time and inefficient development as you relearn the project.

Developers often avoid creating project documentation because they assume it takes a huge effort for which they just don't have time. In fact, you can create a workable project spec in just a few days. It won't be pretty, but it will provide a comprehensive project description that will serve three purposes:

  • Validate your understanding of all aspects of the project.
  • Keep all members of a multi—member project team in sync.
  • Provide a quick way to learn about the project before doing maintenance and updating.

The Table of Contents

Overview of the spec template

Overview

Spec Objectives

Product Description

Configuration Requirements

Hardware Requirements
Software Requirements
Network and Telecomm Requirements

Platform Specification

Platform Notes

Audience Analysis

Subject Matter Expertise
Help System Expertise
Computer Expertise
Effects on Help System Design

File Types

Information Types

Access and Navigation

Graphics Specifications

  Standard Format
  Format Note
  Standard Color Depth
    Color Depth Note
  Types of Graphics
  Capturing Screens

Interface Design

  Interface Design Goals
  General Appearance
Main Window Settings
    Secondary Window 1 Settings
    Secondary Window 2 Settings
    Secondary Window 3 Settings
    Table Settings
    CSS Settings
    Text Attributes
    Template Settings
  Access and Navigation
    Context—Sensitivity/Other Access Settings
    Table of Contents Settings
    Index Settings
    Search Feature/Engine Settings
    Link (Jump and Popup) Settings
    Related Topics List/Button Settings
  Writing
    Writing Styles
  Programmatic
    DHTML Settings
    Javascript Settings
    Audio Settings
    Video Settings
    Animation Settings
  Other
    Control File Settings
    Topic Length Settings
    Other Settings

Development Tool Specification

Development

Structuring the Material
Error Control

Record—Keeping

Online Writing Style Guide

Writing
Structure and Grammar
Minimalism

Hard—Copy Documentation Conversion and Style Guide

Sample Sections

Overview of the spec template

Use this template as a model for the actual specs. Each section of the template begins with an explanatory section in italics that explains that section's purpose. Delete that explanatory text from your actual specs, including this paragraph and heading.

Note that this spec is serving as the initial template for a variety of types of material ranging from online, context—sensitive help to stand—along online documentation. For the sake of brevity, the spec template will simply refer to that material as "the documentation". Change this to a more appropriate term when you create the actual spec.

Overview

This section lists the spec's overall "administrative philosophy". Modify this section as necessary, but the final version should be fairly similar to the boilerplate below.

Read this document carefully before you begin any project.

This document is a template for you, the developer, to use when creating the documentation for a *group name* product. Several notes about this document:

This document does not specify the outline, content, budget, or schedule for any particular project. You must determine those elements for each project.

This document is prescriptive to ensure consistent documentation files and development. You must see the documentation manager before deviating from any specification or procedure here. However...

Circumstances change. The specifications and procedures in this document are accurate as of *date*. If you think that any part of this document needs revision, please see the documentation manager.

This document focuses on online documentation, but you may have to produce hard—copy also. The last part of this document gives instructions for converting the online to hard—copy using *tool name*.

If you must integrate other online documentation with the *documentation* described in this spec, you can use the spec to evaluate the other material to judge how it will mesh with the *documentation*. Finally, you may be able to use this spec to provide guidance to developers in other groups or third—party vendors.

File Types

This section lists and describes the files that make up the project. There are two groups of files to be listed.

The set of files that comprise the deliverable.

The larger set of files that comprises the overall project. Note that this second set of files may vary somewhat depending on the authoring tool(s) used to create the project.

This section's purpose is to ensure that developers know exactly which files to include in the install kit and which files to archive.

This section lists two types of files — the deliverables that comprise the *product name* help system and the files associated with the overall project.

The *product name* documentation deliverable consists of the following types of files:

**

**

**

The overall project, based on *authoring tool name and version number*, consists of the following types of files:

**

**

**

Top of Page

Home

Resources

Services

Contact Information

About Hyper/Word

Format, Usage Rights, Price

Format — The spec template is a Word document which you'll receive online.

Usage rights — Unlimited usage rights within your documentation group, or within your company if there's only one documentation group.

Price — US $25, by check or money order. (Mass. residents please add 5% sales tax.)

 

spacer.gif (91 bytes) Copyright © 2003 Hyper/Word Services
     
   

Neil Perlin
Hyper/Word Services
101 Emily Road
Tewksbury, MA 01876

nperlin@concentric.net

Phone: 978-657-5464