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
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).
• Use a plural heading unless the subject makes sense only in the singular.
• Describe the user’s goal, not the tool that is used to perform the task.
• 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.
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.
• If the prerequisite is explained in another task topic, link to the task topic, and label the link appropriately.
• When you link to a prerequisite task, do not create an inline link that is part of a sentence.
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.
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.
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.
• Place important words at the beginning of a heading to focus attention on those words.
• Do not use a gerund for a concept heading because gerunds indicate tasks.
• Make the topic heading specific enough so that a user who sees it in a list of search results knows what the topic contains.
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.
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.
• 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.
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.
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.
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.
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.
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.
• Specify the title of the topic or section, and provide context for the link.
• 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.
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.
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.
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.
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)
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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