Project Control Documents

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:

**

**

**


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