You should not refer to any front matter or body matter in the glossary. You may refer to other terms within the glossary.
This chapter defines the organization of complex technical documents, such as books, and discusses the following topics:
Each division has a specific function and format, which improves document readability. A reader familiar with the content and structure of one Collective Technologies document will feel comfortable with any other Collective Technologies document.
Structurally, most Collective Technologies complex technical documents have three major components. These components are placed in the document in the order shown in Table 2.
Table 2
Major parts of a complex document
Component Subdivision Front matter Title page Copyright page Revision page Contents Figures Tables Using this book Acknowledgments Text Parts Chapters Sections and subsections Appendices Back matter Bibliography Glossary Index
Major divisions in a document that combines books are called parts. Major divisions within a book are called chapters and appendices. Major divisions within a chapter or appendix are called sections and subsections.
The front matter includes the following:
The title page contains the title, Collective Technologies logo, author or team, document number (if any), edition and revision number, date of publication, audience restrictions and disclaimers (if required), and the name and location of the publisher.
The author information is typically 36 points below the title. The disclaimer title has 72 points of white space above it (between the date and the disclaimer title). The disclaimer paragraph has 144 points of white space below it and the title block has another 96 points of white space above it (for 240 points total space between disclaimer and address blocks). This tends to fill the entire page. These values can be adjusted on an ad hoc basis as needed, should the title or disclaimers or author sections be longer than the versions used to create the templates.
The logo, title, author, document number, revision or edition number, date, and address block are all centered on the page. The restriction block, if any, is aligned left and indented 3 inches.
Document page counting begins with the title page; numbering and footers should not appear, however, until the "Contents" page. Disclaimers are placed between the date and the publisher information.
The copyright page, which appears on the back side of the title page (page ii), contains the standard Collective Technologies copyright statement, as shown on the copyright page of this book. The following items appear on the copyright page in the order shown:
This page, which contains the history of revisions made to the document since its initial release, follows the copyright page. It is almost always page iii of the document (unless the copyright page runs long).
On the first release of a document, the revision sheet contains the edition, the date, and a short description of all changes. On subsequent releases, the revision sheet still lists the editions and dates of previous releases. You may drop previous descriptions of all changes at each new release.
If multiple authors work on a document you should include your name after the date for changes you made. Also include the version number of the software or hardware that the edition documents.
Revisions are placed in reverse chronological order; that is, the latest revision is listed first. Also, if a document has a new title or replaces another document, indicate the former title. The nature of the change description depends on the revision.
Revision sheets must be included in first editions of all documents.
"Contents" is the next component in a complex technical document. It always begins on an odd-numbered page (right-hand side) in double-sided documents. Headers, footers, and page numbers first appear here, in lowercase Roman numerals, even though page counting begins with the title page.
"Contents" lists all part numbers, chapter names, and appendix names, as well as all section and subsection names (the first 3 levels of headings) and page numbers. The page number is separated from the chapter, appendix, section, or subsection title by a row of leaders, evenly spaced dots or periods used to lead the eye across the page.
In proposals and results documents, but not in books, the section and subsection numbers are listed to the left of the section or subsection title (such as "1 Hardware" and "1.1.2 Disk drive size"). An em space is used to separate the section number from the section title. In books, individual sections and subsections are not numbered.
Do not use the word "Table" in the table of contents title. Simply call it "Contents."
The list of figures follows the table of contents and is titled "Figures." The page number is listed to the right of each figure number and figure header (or caption), and is separated with leaders.
All continued figures-those that spread across more than one page-should be listed. When a figure is continued it should retain its figure title.
Do not use "List of" in the list of figures title. Simply call it "Figures."
The first page of "Figures" is always a right-hand (odd-numbered) page in double-sided documents.
The list of tables follows the list of figures and is titled "Tables." The page number is listed to the right of each table number and table header (or caption), and is separated with leaders.
All continued tables-those that spread across more than one page-should be listed. When a table is continued it should retain its table title.
Do not use "List of" in the list of tables title. Simply call it "Tables."
The first page of "Tables" is always a right-hand (odd-numbered) page in double-sided documents.
This front matter section is named "Preface" in proposals and results documents and "Using this book" in books. It usually contains the following information in this order:
The preface should be indexed, if there is an index.
The preface is the first section or chapter listed on the Contents page.
The text of a book contains the following four major components:
When text material may be logically divided into sections larger than chapters, the chapters may be grouped into parts. Parts may be numbered and given a part title (such as "Part 1 Working with Accounts") parts. The part number and title appear on a right-hand (odd-numbered) page; the back side is left blank (including no header or footer). Chapters within parts are numbered consecutively through the book; they are not restarted at 1 within each part.
Part numbers are written in Arabic numerals ("Part 1," "Part 2").
Each part may have an introduction, usually short, and titles, for example "Introduction to Part 2."
Part numbers and their titles are listed in the table of contents.
No part title need precede the back matter of a book divided into parts, but using "Part 5 Appendices" is perfectly appropriate.
When referencing part titles, place the title in quotation marks. For example: Refer to Part 3, "Module Reference."
Part title pages are numbered but do not have page numbers (or anything else) in their footers. The header and footer for part title pages are left blank.
Chapters are used only in books.
A chapter contains a chapter title, an introductory paragraph, and up to 3 levels of text. As a general guideline, try to keep chapters as short as possible and address only one major topic in each chapter.
Chapter titles should be short and describe the chapter contents succinctly. Chapter titles should be task-oriented; starting the title with words like Working, Using, Maintaining, and other similar concepts is strongly recommended.
After the chapter title and before any subsidiary-level heading, there can be a brief overview or introductory paragraph that describes the intents and contents of the chapter.
Divide each chapter into sections (Heading 1) and subsections (Heading 2, Heading 3, Heading 4) by topic. Give each a section header with the appropriate style.
Up to three levels of section and subsection headings are commonly used. More would be confusing. If you need a fourth level, reorganize the chapter to avoid the problem. Keep secondary and tertiary levels to a minimum.
Avoid using single headers. A single header on a structural level indicates a structural defect. Do not give a heading to a topic just to make it stand out.
Headings are not numbered.
An appendix(4) usually includes supplementary matter that is not essential to a document but helpful to a reader seeking further clarification, or for reference material. Often this material is awkward or distracting if presented in the main text. Specifications, long lists, survey questionnaires and responses, and command references and man pages are commonly placed in appendices. Appendices are not mandatory.
Appendices should be indexed, if there is an index.
Back matter includes the following:(4)
Divide the bibliography into two parts:
Both parts of the bibliography should have annotated entries. Annotations should be brief-one to three sentences-and describe content and pertinence of the entry.
Bibliographies are not mandatory. If a document has a bibliography, always place it after the appendices and before the glossary.
A bibliography should be indexed, if there is an index.
A glossary is an alphabetical collection of specialized terms and their meanings within a document. A glossary is intended to stand on its own.
You should not refer to any front matter or body matter in the glossary. You may refer to other terms within the glossary.
Glossaries are not mandatory. If a document has a glossary, always place it after the last appendix or bibliography.
A glossary should be indexed, if there is an index.
The index contains an alphabetical list of topics and page numbers to help readers find information.
Indices only appear in complex books. Simple documents may omit the index.
Templates define page formats. This section deals with general formatting considerations, including the following items:
Captions identify all figures and tables. These captions appear in the "Figures" and "Tables" sections, after the "Contents," and include the figure numbers or table numbers and page numbers along with the caption itself. Some examples:
Figure 1 Current environment
Table 4 Software changes
In documents that are double-sided, the right page footer contains "Collective Technologies" on the left side and the page number on the right side, below a 2-point horizontal rule, in Arial Black 11-point text. The left page footer contains "Collective Technologies" on the right side and the page number on the left side, below a 2-point horizontal rule, in Arial Black 11-point text. Figure 3 and Figure 4 provide sample left- and right complex document page footers.
Figure 3
Footer for left pages of complex documents
122 Collective Technologies
Figure 4
Footer for right pages of complex documents
Collective Technologies 123
If there are any restrictions (such as "Internal Use Only," "Draft," "Private," or "Confidential and Proprietary"), the restriction should appear centered in the footer.
Use footnotes to cite sources of information and to present notes to the reader.
In text, sources are identified immediately following the end of the sentence and the footnote is placed at the bottom of the page.(5) Collective Technologies uses footnotes, not endnotes, for references in most documents. In white papers and conference papers, endnotes may be used at the discretion of the author.
Text footnotes use Arabic numerals (1, 2, 3) as their reference markers.
In tables and figures, identify sources immediately after the table or figure and place the footnote at the bottom of the figure or table.(6)
Footnotes in tables and figures use alphabetic letters (a, b, c) as their reference markers.
In proposals and results documents that are double-sided, the right page header contains the appendix or section title (such as "Section 1 Overview") on the left side, above a 2-point horizontal rule, in Arial Black 11-point text. The left page footer contains the document title on the right side above a 2-point horizontal rule, in Arial Black 11-point text. Sample headers for the left and right pages of a double-sided document are in Figure 5 and Figure 6.
Figure 5
Header for left complex documents
Document Title
Figure 6
Header for right complex documents
Chapter 1 Overview
In books, which are always printed double-sided, headers are omitted.
All headings are in down style-capitalize only the initial letter of the first word. Of course, proper nouns or other words that require capitalization normally, such as vendor names, product names, places, and acronyms, are permitted.
There must be at least two headings at each level where headings are used. There must be at least two subheadings at each level where subheads are used.
Headings are not numbered.
Any notational convention, such as monospace or boldface italic type, that applies to words in the heading is carried over into the heading as well.
Major parts of a book -- title page, contents, figures, tables, using this book, chapters, appendices, bibliographies, glossaries, parts, and index -- should always start on odd-numbered, right-hand pages. Major parts of a proposal or results document -- title page, contents, preface, sections, and glossaries -- should always start on their own pages.
Within chapters and appendices, individual section headers (Heading 1, Heading 2, Heading 3, and Heading 4), should never be isolated from the text they describe. Avoid single lines of text appearing at either the top (called widows) or bottom (called orphans) of the page.
Use of forced page breaks is dictated primarily by whether they contribute to the presentation value of the page. Forced page breaks are permitted and are used at the discretion of the writer.
Forced page breaks are also dictated by the publishing tool used. In some tools, using forced page breaks early in the layout process can complicate things; in other tools, it may be helpful to use forced page breaks to aid in the layout process. Final layout is often more difficult if many forced page breaks exist within the text.
Use blank pages at the end of a chapter so that the book is correctly paginated. Such pages should have a footer and be even-numbered, left-hand pages. (The only exception to this rule is that the reverse (even) side of a Part page must have neither header nor footer.) This allows the first page of each part, chapter, or appendix to begin on an odd-numbered, right-hand page.
Tables that span two or more pages should have table titles and column headings at the top of each continuation page.
When should you being a heading on a new page? The answer involves several considerations, some of which are subjective judgments about document usability or the appearance of the page or pages involved. Other considerations are determined by how the layout serves the organization and presentation of information to the reader.
For all section headings, one possibility is to start a heading on a new page if less that one-fourth of a page remains where the heading would otherwise go.
Use a forced page break to keep the text that introduces a figure or table with that figure or table.
In all cases, number pages consecutively without chapter numbers or appendix letters preceding the page number. For example, avoid 1-4 and 1-5 and use 4 and 5; avoid A-1 and A-2 and use 101 and 102.
Every page -- including blank pages at the ends of chapters -- should have a page number. The exceptions are:
Page numbering first appears on the first "Contents" page (which is a right-hand page in double-sided documents). However, the page count begins from the title page.
All pages through the end of the Preface (or "Using this book") are numbered as lowercase Roman numerals. The page number appears in the footer on the right side on all single-sided and right-hand double-sided pages and on the left side on all left-hand double-sided pages.
The numbering must be in Arabic numerals beginning at the first page of Chapter 1 (either on page 1 if there is no part page preceding Chapter 1, or on page 3 if there is a part page preceding Chapter 1). Appendices, bibliographies, glossaries, and index pages are numbered in the same manner as chapters.
The first page of an appendix, or chapter looks like the following:
The first page of a special section -- Contents, Figures, Tables, Bibliography, Glossary, or Index -- looks like the above, except the gray box with the appendix, chapter, or section number is omitted in its entirety, and the title is the keyword (Contents, Figures, and so on). The title position is at the top of the page.
The first page of the Preface looks like the above, except the gray box with the appendix or section number is omitted in its entirety, and the title is the keyword (Preface). The title position is in the same space as it would be if the gray box were present.
In a double-sided document, a first page must start on a right-hand page.
Left-hand pages in a double-sided proposal or results document look like the following:
For left-hand pages in books, refer to the "Left pages for books" section.
Right-hand pages in a double-sided proposal or results document look like the following:
For right-hand pages in books, refer to the "Right pages for books" section.
Left-hand pages in a double-sided book look like the following:
For left-hand pages in proposals and results documents, refer to the "Left pages for non-books" section.
Right-hand pages in a double-sided book look like the following:
For right-hand pages in proposals and results documents, refer to the "Right pages for non-books" section.
![[Contents]](/icons/buttons/toc.gif){kind=icon}
Jump to table of contents
![[Back]](/icons/buttons/previous.gif){kind=icon}
Back to Chapter 1, "Simple technical document structure"
![[Next]](/icons/buttons/next.gif){kind=icon}
Onward to Chapter 3, "Methodology document structure"
![[Note]](/icons/buttons/lightbulb.gif){kind=icon}