Chapter 4. Structure

Follow these guidelines to present information in a clear and logical structure.

Topic-based information

Topic-based writing is an approach to writing well-structured, minimalist information that is usually presented online.

A topic is an independent unit of information with the following characteristics:

• It is meaningful when it is displayed alone.

• It follows the rules for a specific topic type.

A book establishes a progression of information that readers are expected to follow in a sequence. By contrast, online information encourages readers to approach topics from various directions. Writers of online information divide information into topics that can be read independently.

There are three main topic types:

Task

Concept

Reference

For more information, see DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA, Chapter 1, “Topic-based writing in DITA,” and Developing Quality Technical Information, Chapter 8, “Organization.”

Task topics

Task topics document the steps that users must complete to accomplish a task or goal.

Task topics provide procedures, typically in step-by-step instructions. Some task topics might list choices as bulleted points rather than steps, or they might describe a single action rather than a sequence of steps. Task topics also provide information about the context (where to perform a task and when), the rationale (why to perform a task), prerequisites, and examples.

Supertasks (high-level tasks) are the starting points for most users. Steps in a supertask often link to individual task topics. These tasks can be part of one supertask or many. For example, in database application programming, opening a database connection is a task that can be reused in several high-level application programming tasks.

As you write task information, note what concepts need to be documented, and to what depth, for users to complete the tasks successfully. Consider the probable skills and experience of users, and write with those characteristics in mind. For example, if users must configure TCP/IP and might not know about routers, create and link to a concept topic about routers.

If there are multiple ways to perform a task, consider documenting only the simplest or most common way. For example, you might explain how to do something from the main menu only and assume readers will discover that they can launch the same action by right-clicking an object, by dragging an object, or by clicking a toolbar button. The goal of minimalist writing is to reduce the amount of reading that users must do before they can successfully complete a task. If you must document alternative methods, document them in separate topics. For example, you might write two topics to cover importing data by using a GUI and importing data by using a command line. If you believe that an alternative is not intuitively obvious and you can document it in one sentence, include it as a tip after the main list of steps.

Headings of task topics

Task topic headings must be precise, distinct, and clearly convey what the task is.

Follow these guidelines when you write task topic headings:

• Start the heading with a gerund phrase (a phrase that starts with an -ing verb).


Examples (incorrect)

Create database table

How to start the content integration server



Examples (correct)

Creating database tables

Starting the content integration server


• Use a plural heading unless the subject makes sense only in the singular.


Examples (incorrect)

Deleting an archive for BRMS

Adding a disk to a Linux partition



Examples (correct)

Deleting archives for BRMS

Adding disks to a Linux partition


• Describe the user’s goal, not the tool that is used to perform the task.


Examples (incorrect)

Using the team server installation utility

Working with security tokens



Examples (correct)

Installing the team server

Protecting your system by using security tokens


• Make the topic heading specific enough so that a user who sees it in a list of search results knows exactly what the topic contains.


Example (incorrect)

Configuring components



Example (correct)

Configuring HTTP proxy servers on Linux systems


Structure of task topics

Task topics follow a structure that can vary depending on the task. Start the task with a brief introduction. Next, if required, include prerequisites. Then, list all the steps to complete the task.

You can include a small amount of conceptual or reference information in a task if that information is directly related to the task. For larger amounts of conceptual and reference information, create separate topics, and link to them.

Introductions for task topics

Start a task topic with an introductory paragraph that specifies the purpose or rationale for performing the task.

If the title of the task does not fully convey the context, effect, or objective of the task, provide that information in the introduction. Mention any restrictions that limit the user’s ability to complete the task. If necessary, clarify who performs this task and under what circumstances.

Prerequisites for task topics

A prerequisite is any requirement that must be met, any task that the user must perform, or any authority or privilege that must be set up before the user can start the current task. Not all tasks have prerequisites.

Follow these guidelines:

• List the prerequisites before the first step of the task.


Example

You must have SYSADM authority or CREATE privilege on the table.

1. Start the Administration utility...


• If the prerequisite is explained in another task topic, link to the task topic, and label the link appropriately.


Example

Prerequisite

Creating a connection


• When you link to a prerequisite task, do not create an inline link that is part of a sentence.


Example (incorrect)

Prerequisite

Before you can access the LAN on the system, you must Create a new connection.



Example (correct)

Prerequisite

Before you can access the LAN on the system, you must create a new connection.

See Creating a connection for instructions.


Ending a task

At the end of a task, ensure that users know what to do next if the current procedure is one task in a series by providing a link to the next task topic.


Example

1. In the object navigator, click System > Network > IP Policies.

2. Right-click Virtual Private Networking and click Start.

Next: Testing the VPN connection


Steps in task topics

Use ordered (numbered) lists to describe tasks with more than one sequential step. For detailed information about writing steps, see “Procedures” on page 84.

Length of task topics

Short tasks are typically easier to follow than long ones.

Try to limit the number of steps to nine. If you have trouble reducing the number of steps, try to find ways to chunk the task into subtasks.

Include only necessary conceptual or reference information in a task. Advanced users will be distracted by extra information. Add the lengthy conceptual and reference information to other topics, and provide links to that information from the task topic.

Example of an effective task topic

This example shows a correct task example. This task topic is effective for the following reasons:

• The topic title uses a gerund.

• There is a clear introduction.

• The introduction specifies the purpose and rationale for doing the task.

• The prerequisite is included after the introduction and before the first step, and “Starting TCP/IP” is a link because the information is in a separate topic.

• All steps direct users where to go and what to do to complete the task.

• Steps 4 and 5 explain the purpose of a step before describing the action that the user should perform to complete the step.

• The “Tip” is not a step because it is not part of the procedure to start a connection, but is instead additional information.

• The next task that the user must complete to start a VPN connection is listed as “Next” instead of as a step or a related link.


Example

Starting a VPN connection

To allow remote systems to connect to your local resources, you can start a virtual private network (VPN) connection on your system by using iSeries Navigator.

Prerequisite

Starting TCP/IP

To start a VPN connection:

1. In iSeries, click Server > Network > IP Policies.

2. Right-click Virtual Private Networking and click Start.

3. Click Virtual Private Networking > Secure Connections > All Connections.

4. In the right pane, right-click the connection that you want to start and click Start.

5. Verify that the Status column displays Started by refreshing iSeries Navigator. Click File > System > Refresh.

Tip: To start multiple connections, select each connection, right-click the selected group, and then click Start.

Next: Restarting the system


For more information, see DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA, Chapter 2, “Task topics” and Developing Quality Technical Information, Chapter 2, “Task orientation.”

Concept topics

Concept topics explain ideas that the user must understand to complete a task.

Every concept topic performs at least one of the following functions:

• Introduces a solution, process, product, tool, or feature

• Provides background information and explains issues that users must know before working with a system or component or before starting a task

• Describes the benefits of using one approach rather than another or provides information about when one particular choice or tool is more appropriate than another

• Describes how one feature, tool, or product is related to others and how they work together or do not work together

• Describes any restrictions that limit the circumstances in which a tool can be used successfully

• Explains a glossary term in more detail

• Explains how and why some behavior changes as time passes or work progresses

• Helps users form a mental picture that builds on the experience and knowledge that they are already likely to have

Users typically read conceptual material before beginning a project or starting to use a product or tool. In contrast, users need task or reference topics when they perform a task.

Use minimalist writing techniques to create content that users can quickly understand. Do not attempt to explain the whole design philosophy of a product or component in a single concept topic.

Headings of concept topics

The heading for a concept topic must be a specific, meaningful noun or noun phrase.

Follow these guidelines when you write concept topic headings:

• Use the plural forms of nouns unless the subject makes sense only in the singular.


Examples (incorrect)

Buffer pool

Authentications



Examples (correct)

Buffer pools

Authentication


• Place important words at the beginning of a heading to focus attention on those words.


Example (incorrect)

Overview of installation for web servers



Example (correct)

Web server installation overview


• Do not use a gerund for a concept heading because gerunds indicate tasks.


Examples (incorrect)

Working with the WebFacing Tool

Working online and offline



Examples (correct)

WebFacing tool

Advantages of working online or offline


• Make the topic heading specific enough so that a user who sees it in a list of search results knows what the topic contains.


Examples (incorrect)

Environment

Requirements



Examples (correct)

Client-server environment

Security requirements


Structure of concept topics

Write most conceptual information in paragraphs and unordered lists.

If the explanation is long and complex, use subheadings to break the concept into sections. Use unordered lists when lists are appropriate; numbered lists typically indicate a task. Tables are common elements in reference topics and generally are not appropriate in concepts. Exceptions include tables that indicate when to use specific components or features.

Concepts are likely to be unfamiliar to users, so begin with a definition. Then, expand that definition into an explanation of the things that users must know about the subject. If you are describing a component, feature, or tool, explain its benefits and note any limitations or corequisites for using it. If you are describing a high-level concept, introduce the related lower-level concepts.

Graphics are often helpful in simplifying the explanation of processes or in showing the relationships among components of a product. However, make sure that they serve a useful purpose and are done well. A poor diagram might confuse rather than clarify and can detract from the quality of the information. When you include graphics in topics, ensure that they conform to accessibility and translation requirements.

Length of concept topics

A concept topic must address only one complete idea.

In many cases, it makes sense to divide a large subject (for example, database objects) into an overview topic that links to topics about subsidiary concepts, such as tables, table spaces, and buffer pools. However, do not divide information about a single concept unnecessarily. Users often print concept topics to read them, so ensure that a topic includes all the essential information about the subject that you are covering. In general, keep concept topics to fewer than seven printed pages.

Example of an effective concept topic

This example shows a well-written concept topic. This concept topic is effective for the following reasons:

• The heading is a noun or phrase.

• The introduction (short description) explains why the concept is important to understand.

• The structure consists of paragraphs and unordered lists.

• A definition is used to introduce a new concept or related concept.

• The topic is relatively short but conveys the necessary information.

• Related links are provided; no inline links are used.


Example

Buffer pools

Buffer pools are an important memory component. When used correctly, buffer pools can improve the performance of your database.

A buffer pool is memory that is used to cache table and index data pages as they are read from disk or modified. Data can then be accessed from memory instead of from disk. Because memory access is much faster than disk access, the less often the database manager needs to read from or write to a disk, the better the performance. Because most data manipulation occurs in buffer pools, configuring buffer pools is the single most important method of tuning. Only large objects and long field data are not manipulated in a buffer pool.

When an application first accesses a row of a table, the database manager places the page that contains that row in the buffer pool. The next time an application requests data, the database manager searches for the data in the buffer pool. If the requested data is in the buffer pool, that data can be retrieved without disk access. This method of accessing data results in faster performance.

Pages remain in the buffer pool until you shut down the database or until the space that is occupied by a page is required for another page. The following criteria determine which page is removed to bring in another page:

• How recently the page was referenced

• The probability that the page will be referenced again by the last agent that accessed it

• The type of data on the page

• Whether the page was changed in memory but not written out to disk

Related tasks

Creating a buffer pool

Related reference

Buffer pool commands


For more information, see DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA, Chapter 3, “Concept topics.”

Reference topics

Reference topics provide quick access to information that users need to complete tasks.

Reference topics typically provide users with information about the following types of elements:

• APIs

• Classes

• Commands

• INI settings

• Keyboard shortcuts

• Language elements

• Parameters

• Protocols

• Schemas

• Statements

• Symbols

• Templates

Document the purpose of each reference element. Include restrictions (such as case sensitivity), necessary authorities, and anything else that might limit the use of that element.

Assume that users who use reference topics already understand the basic technology. Provide brief statements of fact rather than lengthy explanations. Make reference topics easy to scan because users typically look for reference material only when they need it, rather than studying and learning it as they do with concepts.

Headings of reference topics

The headings for reference topics are typically nouns or noun strings.

Follow these guidelines when you write reference topic headings:

• Do not begin a heading with an article (a, an, or the).

• Use the plural forms of nouns unless the subject makes sense only in the singular.


Examples (incorrect)

Configuration parameter

Sample output reports



Examples (correct)

Configuration parameters

Sample output report


• Title the topics for a particular category of reference information consistently. For example, if you have multiple topics about parameters, title all of those topics consistently.

• Use the name of the reference element in the title, and provide descriptive text to clarify the meaning of cryptic element names. In addition to clarifying the subject of the topic for English-speaking users, the descriptive text can be translated so that non-English-speaking users understand the subject of the topic as well.


Example

chgwtr: Change writer command


Structure of reference topics

For a particular category of reference information, use a consistent format so that users can find information quickly.

Reference topics often include subsections to help users locate particular information. For example, you can organize command reference topics by using “Purpose,” “Syntax,” “Parameters,” and “Usage” subsections.

When the topic heading requires explanation, provide introductory information to help users quickly determine whether they want to read more.


Example

org.eclipse.core.resources package

The org.eclipse.core.resources package provides basic support for managing a workspace and its resources.


You can also use tables and bulleted or definition lists to help users scan for information quickly.

Provide links to closely related reference topics, and, in some cases, to related concept and task topics.

Length of reference topics

Keep reference information brief and formulaic, but include all necessary information. Make reference information easy to scan to help readers find information quickly. Do not write long explanations; assume that readers understand the basic technology.

Example of an effective reference topic

This example shows a well-written reference topic. This reference topic is effective for the following reasons:

• The information states only the facts about the command and does not include task or concept information.

• The heading and introduction are clear and in a form that users can identify easily.

• All links are referenced correctly in the related links section at the bottom of the topic.

• Information is easy to scan and locate because of subheading links.


Example

UPDATE TRACETABLE command

The UPDATE TRACETABLE command changes the trace level setting for the requested trace tables.

Syntax

>>-+-UPDATE-+--+-TRACETABLE-+---------------------------->
   '-UPD----' '-TRTAB------'
       .-,---------------------.
       V             |
>—NAME(---+-trace_table_name--+-+-)--+------------+----><
      '-trace_table_name*-' '-OWNER(-+-BPE--+-)-'
                            +-SMDC-+
                            '-SMUI-'

Parameters

UPDATE | UPD

A required parameter that specifies that the action against the trace table is to update its attributes.

TRACETABLE | TRTAB

A required parameter that specifies that the resource type being acted upon is a BPE-managed trace table.

NAME (trace_table_name)

A required parameter that specifies the name of the trace table type or types to update. You can specify a single trace table name or a list of trace table names separated by commas. Trace table names can contain wildcard characters. Trace table names can be BPE-managed trace tables or they can be trace tables that are managed by IMS™ Sysplex Manager.

The following trace table types are available:

AWE

Asynchronous work element (AWE) trace table

CBS

Control block services trace table

CMD

Command trace table

DISP

Dispatcher trace table

LATC

Latch trace table

SSRV

System services trace table

STG

Storage service trace table

You can update trace tables only for IMS Sysplex Manager address spaces.

OWNER(BPE|SMDC|SMUI)

An optional parameter that specifies the owner of the trace table type or types that you want to update. You can specify one of the following values:

BPE

BPE-defined trace table types

SMDC

Data Collector-defined trace table types

SMUI

Server-defined trace table types

Related tasks

Changing trace level settings

Related concepts

Trace tables

Related reference

UPDATE TRACETABLE command output


For more information, see DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA, Chapter 4, “Reference topics.”

Links in topic-based information

Links are an important navigational aid in topic-based information because they are immediately available and the user does not have to scan an index, search results, or table of contents.

One way to help users find what they want in online information is to provide links to other topics that are closely related. However, use restraint when providing links. Too few links can force the user to waste time searching for critical information. If too many links exist, users waste time following links that they do not need for their immediate purpose. Maintaining a large number of links can become a difficult task.

General guidelines

Follow these general guidelines when you use links in topic-based information:

• In every topic, try to provide at least one link to another topic.

• In general, place links at the end of each topic. Exceptions to this rule are described in “Inline links” on page 130.

• Link only to closely related information, which includes the following types of information:

• The parent topic, which is particularly useful to users who come to the current topic from a list of search results

• The previous or next topic in a series of subtasks

• A topic that explains a concept that users must understand before reading the current topic

• A topic for a task that is mentioned in the body of the current topic

• A sample that is related to the current topic

• In the case of a supertask (high-level task), topics for steps in the supertask

• Do not include more than 10 links in any topic, and do not include more than five links to one information type (concept, task, or reference).

Links to related topics

Place most links at the end of the topic under the appropriate subheading: “Related concepts,” “Related tasks,” “Related reference,” and “Related information.” For example, if you link to a concept topic, place the link in the “Related concepts” section. Use “Related information” for links to tutorials, scenarios, and web-based resources. Many topics do not need links to all categories, but most topics should provide at least one link from one of the four categories.

The text of the link should provide enough information for the user to decide whether to look at that topic. In most cases, the link text should match the topic heading that it refers to.

List the links in the following order:

Related concepts

List links in order of relevance to the current topic, starting with the most relevant link, or follow the order in which the concepts are mentioned in the current topic.

Related tasks

List links to task topics in the order in which the tasks are likely to be performed.

Related reference

List links in alphabetical order unless there is a good reason for another sequence.

Related information

List links in order of relevance to the current topic, starting with the most relevant link.

Links to subheadings

In a long concept, reference, sample, or tutorial topic, you can provide links at the beginning of the topic to subheadings later in the topic. Do not use subheadings in task topics; task topics should be short and specific.

Linking to subheadings helps readers to quickly grasp the content in a topic and move directly to the part that interests them. If you include a list of subheadings in a topic, place the list after the introductory paragraph and provide an introductory sentence.


Example

Detailed information about the parameter types are in the following sections:

Configuration parameters

Performance parameters

Security parameters

Storage parameters


Inline links

Inline links are links within the running text of a topic. When you create inline links, follow these guidelines:

• Use inline links sparingly. Inline links can frustrate users by distracting them from the topic that they are currently reading. Use an inline link only if you expect the user to leave a topic at a particular point to read a required piece of related information. Instead of using inline links, use related links as much as possible.

• Try to limit the use of inline links in task topics to prerequisite tasks, to the next task in a sequence, and to subtasks that are cited as steps.

Prerequisite tasks

If you identify a prerequisite for a task that is documented in its own topic, provide a link to that prerequisite topic before the list of steps. Do not repeat these links in the related links at the end of the topic.

Subtasks

Consider putting all or many of the steps in a large task into separate task topics. For example, “Configure the server” might be step 2 in one task, but the five steps that are needed to configure a server are described in a separate topic called “Configuring servers.” In that case, make the whole text of step 2 a link to the more detailed task topic. Expert users do not have to follow the link to the detailed instructions, but less-experienced users can. Structuring information in this manner also makes it easier to reuse it in multiple places.


Example

1. Start the server.

2. Configure the server.


Next task in a sequence

If the current task belongs to a sequence of tasks, provide a link to the topic about the next task in that sequence. Do not repeat this link in the list of related tasks at the end of the topic.


Examples

What to do next

Complete the steps in Deploying your project.

Next topic: Deploying your project


• Specify the title of the topic or section, and provide context for the link.


Examples

For a complete list of supported operating systems, see Requirements.

If you cannot restart the server, see Troubleshooting for possible causes and solutions.


• Keep the structure of any sentence that contains an inline link short and simple. When sentences are translated into other languages, the order of the words is often rearranged.

• Never use click here as the link text.


Example (incorrect)

For more information about storage, click here.


For more information, see DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA, Chapter 7, “Linking” and Developing Quality Technical Information, Chapter 9, in the section “Link appropriately.”

Books

Books and publications that follow a book structure typically contain front matter, a body that is divided into sections, and back matter.

Sequence of book elements

Place elements in the following order in books and publications that follow a book structure:

1. Front cover

2. Title page, the back of which includes the edition notice and copyright statement

3. Table of contents

4. List of figures (optional)

5. List of tables (optional; can be combined with the list of figures)

6. Safety and environmental notices, if required

7. Preface

8. Summary of changes (optional)

9. Definition of symbols (optional)

10. Body (text)

11. Appendixes, including an appendix titled Accessibility (unless you include the required accessibility information elsewhere)

12. Hardware warranty (if applicable)

13. Legal notices

14. Glossary (optional)

15. Bibliography (optional)

16. Index

17. Reader comment form (optional)

18. Back cover

If a publication is divided into separate volumes, each volume is treated as a separate book, and each book must contain all required elements.

Book elements and other items that might be included in a book

Chapter titles

A chapter title consists of the word Chapter, an Arabic numeral followed by a period, and descriptive wording. Like other headings, apply sentence-style capitalization to the chapter title. Chapter numbers simplify cross-references and make it easier for the reader to find headings.


Example

Chapter 1. Introduction to InfoBase


Page numbering

Use consecutive pagination through an entire book, excluding only the front matter. Use lowercase Roman numerals for paginating front matter, excluding the title pages, notices page, and blank pages. Use Arabic numerals for body content.

Exception: Use folio-by-chapter numbering (chapter-based page numbering) in situations where one book is published with several languages in the same book. Because each language can take a different number of pages and the writer creates only one language version of the information, the writer cannot know how many pages are in each translated chapter.

Form numbers

Form numbers are assigned to items, including publications, that can be ordered.

Parts and part titles

Divide a book into parts if a logical grouping of related chapters makes the information in the book easier to understand and retrieve. For example, an application programming guide and reference has guidance information as Part 1 and reference information as Part 2.

A part title consists of the word Part, an Arabic numeral followed by a period, and descriptive wording. Like other headings, apply sentence-style capitalization to the part title.


Example

Part 2. System administration


Follow the practice in The Chicago Manual of Style of numbering chapters consecutively; do not begin with Chapter 1 in each part. If you divide a book into parts, you can present the appendixes and back matter in either of the following ways:

• Present the appendixes as a separate part (titled Part n. Appendixes) and the glossary, bibliography, and index in another part (titled Part n+1. Glossary, bibliography, and index).

• Present the appendixes and back matter in one part (titled Part n. Appendixes, glossary, bibliography, index). This method is preferable if there is only one appendix. If you divide a book into parts and there are no appendixes, do not place the back matter within a part.

Do not divide a book into parts if the main text is one part and the appendixes and back matter are the only other parts.

Running headers and footers

Running headers and footers help readers easily locate their place in the book. As the names imply, running headers are displayed at the top of a page, and running footers are displayed at the bottom.

Running headers

The use of running headers is optional. Use running headers to help the reader find information quickly. If you use running headers, follow these guidelines:

• Do not duplicate the chapter title.

• Use header text that is helpful to the reader. When there is more than one heading level on a page, use the most meaningful text as the running header.

• Do not use running headers when the header changes on every page.

• Indicate the content that is described on the page. The wording of the running header must correspond to the text heading, but does not have to be identical.

• Use running headers throughout a book, not just in specific chapters. Use running headers throughout a library if appropriate.

If your authoring tool supports the process, omit running headers from these pages:

• Part title pages

• Chapter title pages

• Any page that displays the equivalent of a chapter title, such as the first page of the table of contents, preface, appendix, notices, glossary, and bibliography

However, you can use a running header on a page that contains only an illustration or a table. Ensure that the material in the illustration or table pertains to the topic of the running header.

Running footers

Running footers are required and are usually generated for the copyright notice, the book title, and the chapter title by your text processor. If they are not, use the following format:

• The footer for the copyright notice must be displayed on any page that includes the equivalent of a chapter title, such as the first page of the table of contents, preface, appendix, notices, glossary, and bibliography.

• The footer for the book title must be displayed on the left page following the equivalent of a chapter title.

• The footer for the chapter title must be displayed on the right page following the equivalent of a chapter title.

Titles of publications

Create publication titles consistently within a product library. A title must give an idea of the tasks that users can accomplish by reading the publication or indicate other specific information that the publication contains. Include the following elements in each title:

• The product name, including the name of the operating system or systems, if any

• A term or terms that describe the supported tasks or other specific information that the publication contains (for example, Administration, Planning and Installing, or User)

Optional: An additional term that indicates the type of information (for example, Guide or Reference)


Examples

IBM TotalStorage Enterprise Tape System 3590 Introduction and Planning Guide

Administration Reference for IBM DB2

IBM Clientware for iSeries: Administration Reference I Part 2.


Version and release

Include the version and release in the short title of an online book because they are used to identify the level of the book. Generally, do not use the version and release in the title of a printed book, but include the version and release on the cover and title page. When you provide a cross-reference to a book, include the version and release levels only if there is a good reason to do so, for example, if two versions of a product are available simultaneously. In this case, use the format Product name, Version x.y book title.

Type size in printed documentation

Follow ISO Standard ISO/IEC 18019, clause 9.3.1 (Presentation of text) Typefaces and Sizes, which states to use a type size that corresponds to a minimum of 9 points and a maximum of 11 points. The same rule applies to the entire front and back matter of a publication.

Books: Front matter

The front matter of a book consists of all items after the front cover and up to, but not including, the body.

Sequence of front-matter elements

Place front-matter elements in the following order in books and in publications that follow a book structure:

1. Title page, the back of which includes the edition notice and copyright statement

2. Table of contents

3. List of figures (optional)

4. List of tables (optional; can be combined with the list of figures)

5. Safety and environmental notices, if required

6. Preface

7. Summary of changes (optional)

8. Definition of symbols (optional)

Front-matter elements

Edition notice and copyright statement

The edition notice and copyright statement are displayed on the back of the title page. The edition notice indicates the version of the product that the book applies to and which previous edition of the book is replaced by the current edition. The edition notice is followed by the copyright notice for the book.


Example

This edition applies to Version 2 Release 3 of IBM DB2 Bind Manager for z/OS® (product number 5655-E43) and to all subsequent releases and modifications until otherwise indicated in new editions.

This edition replaces SC27-1450-07.

© Copyright IBM Corporation 2000, 2011. US Government Users Restricted Rights – Use, duplication, or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.


Always use the legally approved boilerplate text for your edition notices.

Table of contents

Use the heading Contents for the table of contents. Check the style sheet for your library to determine how many levels of headings to include in the table of contents for your book.

In a large book, you can include a partial table of contents for each part or even for each chapter if it helps the reader.

Use leader dots in the table of contents.


Example

Contents

About this information . . . . . . . . . . . . . . . . . . . . . . . . . . . v

Service updates and support information . . . . . . . . . . . . . v

Highlighting conventions . . . . . . . . . . . . . . . . . . . . . . . . . v

How to look up message explanation . . . . . . . . . . . . . . . . vi

Searching an information center . . . . . . . . . . . . . . . . . . vi

Using a web search . . . . . . . . . . . . . . . . . . . . . . . . . . . vi

Chapter 1. DB2 Bind Manager overview . . . . . . . . . . . . 1

DB2 Bind Manager components . . . . . . . . . . . . . . . . . . . . 2

DB2 Bind Manager features and benefits . . . . . . . . . . . . . 2


List of figures

A figure can be an illustration, a chart, a screen capture, or a photograph. Consider the following criteria to determine whether to include a figure list:

• Consistency. If other books in your library use a list of figures, include one in your book.

• Number of figures. If you have a large number of figures, include a list.

• Placement of figures. If you cannot always place the figures in your book at the point in the text where they are pertinent, include a list.

When you use a figure list, follow these guidelines:

• Use the heading Figures for the figure list.

• Do not repeat the word Figure in each entry in the figure list.

• If a figure has a long caption, use a shortened caption in the figure list.


Example

Figures

DB2 archive log offload processing 5

DB2 Archive Log Accelerator environment 7

DB2 Archive Log Accelerator main menu 16


List of tables

Consider the following criteria to determine whether to include a table list:

• Consistency. If other books in your library use a list of tables, include one in your book.

• Number of tables. If you have a large number of tables, include a list.

• Placement of tables. If you cannot always place the tables in your book at the point in the text where they are pertinent, include a list.

• Table captions. If you caption the tables as figures, include them in a figure list rather than a table list.

When you use a table list, follow these guidelines:

• Use the heading Tables for the table list.

• Do not repeat the word Table in each entry in the table list.

• If a table has a long caption, use a shortened caption in the table list.


Example

Tables

Started task JCL modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Optional started task parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Message severity codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16


Safety and environmental notices

Safety and environmental notices are usually required for hardware products. Contact the Safety and Environmental personnel in your organization for assistance.

Preface

A book should have either a preface or an introductory chapter that describes the purpose and audience for the book, as well as any other aspects of the book that readers might need to effectively use the information in the book.

Use About this publication or About this information as the heading of the preface. Start the preface with a brief description of the book (not the product). Explain the purpose and contents of the book. Include information such as supported tasks, level of detail, and what the reader will learn or be able to do as a result of reading the book. If readers might expect content that is not covered in your book, explain that the content is documented elsewhere, and, if possible, let readers know where they might find that content.

Include the following sections within the preface, or create your own; the goal is to use consistent sections throughout a product library. You can include other sections if they are about the book rather than about the product.

Intended audience

Identify the intended audience for the content and any expected prerequisite knowledge.

Conventions and terminology

Explain any special style conventions, terminology, notices, or presentation techniques that you use in the book, such as naming conventions that are particular to some programming languages or visual cues to help the reader recognize different kinds of information.

Prerequisite and related information

Separate required reading and related information. Include the titles and document numbers of all publications.

How to send your comments

Include a section that explains how to provide feedback, as shown in the following example. Alternatively, if your book includes a reader comment form in the back matter, include a cross-reference to that form.


Example

Your feedback is important in helping to provide the most accurate and highest quality information. To submit any comments about this book or any other product name documentation:

• Go to the title home page at http://your feedback page URL. There you will find the feedback page where you can enter and submit comments.

• Send your comments by email to comments@your feedback page URL. Be sure to include the name of the book, the part number of the book, the version of product name, and, if applicable, the specific location of the text that you are commenting on (for example, a page number, a table number, or a heading).

• Complete one of the forms at the back of this book and mail it, send it by fax, or give it to an IBM representative.


Explanation of conventions

If you use nonstandard icons, fonts, colors, or other visual cues for different kinds of information, explain these conventions in the preface or in a separate section in the front matter.

Some books that describe commands or programming language syntax explain their conventions for syntax diagrams in the preface or introduction. For more information, see “Command syntax” on page 187.

Do not explain conventions in the preface if they are used in only one chapter. Explain the conventions in the introductory text of the chapter in which you use them.


Example

Conventions

This book uses the following highlighting conventions:

Bold font indicates commands or user interface controls.

Monospace font indicates examples of text that you enter exactly as shown.

Italic font indicates variables that you must replace with your own values. Italic font is also used to indicate book titles and to emphasize significant words.


Summary of changes

The front matter can include a summary of the changes that were made between versions of the document. Organize the summary of changes in reverse order, starting with the most recent changes. Do not include revision bars in the summary of changes.

Definition of symbols

Explain any symbols that you use to indicate special handling of product components. For example, a symbol is often used to indicate that batteries must be recycled or discarded according to applicable local and national regulations.

Books: Back matter

The back matter of a book consists of all items after the body and before the back cover.

Sequence of back-matter elements

Place back-matter elements in the following order in books and in publications that follow the structure of a book:

1. Appendixes, including an appendix titled Accessibility (unless you include the required accessibility information elsewhere)

2. Hardware warranty (if applicable)

3. Legal notices

4. Glossary (optional)

5. Bibliography (optional)

6. Index

7. Reader comment form (optional)

Back-matter elements

Appendixes

An appendix consists of material that supports the information in the book but meets one or more of these criteria:

• The information is not required for the user to accomplish tasks or to understand the material in the body of the book.

• The information is relevant to only specific situations or to a subset of users.

• The information is primarily reference information.

Place appendixes after the last chapter in the book, in the order in which they are referred to in the body. If the legal notices are included in an appendix instead of in a separate chapter or section, they must be the last appendix.

When a book has only one appendix, use Appendix as the title, followed by a period and descriptive wording. When a book has more than one appendix, start the title of each appendix with Appendix, followed by an uppercase letter (starting with A), a period, and descriptive wording.


Example

Appendix A. Performance considerations

Appendix B. Conversion tables


If you divide a book into parts, you can present the appendixes and other back matter in either of the following ways:

• Include the appendixes in a separate part that is titled “Part n. Appendixes,” and include the glossary, bibliography, and index in another part that is titled “Part n+1. Glossary, bibliography, and index.”

• Include the appendixes and other back matter in one part that is titled “Part n. Appendixes, glossary, bibliography, index.” This method is preferable if a book contains only one appendix.

Legal notices

Include any legal notices that apply to the product either as the last appendix or as a separate topic after the last appendix. Always consult your legal representative to determine the appropriate legal notices to include.

Glossary

Include a glossary if you have a significant number of terms that you must define for your users. For more information, see “Glossaries” on page 245.

Bibliography

A bibliography is not required, but it can be useful in a book that references many publications. A bibliography can include publications that are cited in the book and publications that deal with the same subject as the book.

Index

Indexes are required elements in IBM books. For more information about indexes, see “Indexes” on page 255.

Reader comment form

A reader comment form is a mechanism that readers can use to provide feedback about a book. One side of a typical reader comment form includes the following elements:

• The title and version of the book

• A series of questions that relate to different aspects of the book (for example, overall satisfaction with the book, accuracy of the information in the book, and satisfaction with the completeness of the information in the book)

• Space for the reader to write specific comments about the book

The other side includes information about where to send the form.

White papers

A white paper is a detailed or authoritative report on a specific subject that is written by an expert and can be published for an internal or external audience.

Structuring your paper

A white paper has the following components, in this sequence:

1. Publication information: The title, authors, publication date, and the copyright statement identify the publication. You might want to include author information such as a job title and contact address. When you write about a product, you might have to include the version number. In a short paper up to approximately 10 pages, the publication information can be on the first page; a longer paper requires a cover page.

2. Table of contents: If the paper has more than six subsections, include a table of contents with a list of all the headings, to make the topics easier to access in a PDF file. If the paper is viewed online, make sure that each heading in the table of contents links to its section.

3. Introduction or abstract: Briefly describe the topic, including the aspects that are discussed in the paper. Write this information after you write the paper. Call this section an Introduction or Abstract. In the first or second paragraph, describe your target audience, for example, system administrators, database administrators, or application programmers.

4. Body of the paper: Use headings to help readers follow the content organization of the paper. Use only the number of heading levels that are needed to make your organization easy to understand.

5. End matter (as needed): You might want to include a conclusion and a question-and-answer section. Add appendixes, a list of references, a glossary, and links to related information as needed.

6. Notices: Include standard, required legal notices as defined by your company. Special wording might be required for beta products, performance benchmarks, special projects, and products that include vendor material. Consult your company legal representative for specific wording, if necessary. Include a copyright statement.

If you intend to distribute your white paper outside of your company, follow appropriate trademark guidelines. Specifically, note these details:

• Use trademarked terms correctly.

• Mark trademarked terms correctly with registered trademark (®) and trademark (™) symbols. How terms are marked depends on where you intend to distribute the information.

Writing your paper

Follow these guidelines for the body of your paper:

• Follow style guidelines for writing style, highlighting, and punctuation.

• If your white paper has listed authors and describes the actions or opinions of those authors, the use of first person might be acceptable. If you are unsure whether your white paper warrants the use of the first person, ask an editor.

• If you must refer to the paper itself, use the term paper, not white paper or document.

• Break the information into tables and lists where appropriate. Use bulleted lists unless the order of the information is important.

• Do not use symbols, especially in book titles or product names.

• Use diagrams to illustrate your points where appropriate.

• Include captions for tables and diagrams.

• To cite a publication in a product library, use cross-references.


Example

For additional background information about datagram sockets, see System p® and AIX Information Center located under Documentation at www.ibm.com/servers/aix/library.


Getting your paper reviewed and edited

As you write your white paper, ensure that the appropriate people review it to verify that it is accurate, complete, and legally appropriate. After you are satisfied with the content, have your paper edited. Because more than one group is often involved in developing a white paper, clarify your roles from the outset. Be sure to get your white paper approved, using the approval process in your organization.

A typical approval process includes the following people:

• A technical contact or appropriate subject matter expert

• A product marketing representative

• Your manager

• A technical editor

• A company legal representative

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.15.229.161