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

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

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:

**

**

**

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

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

nperlin@concentric.net

Phone: 978-657-5464