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 simple technical documents, such as proposals and results documents, 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 simple Collective Technologies technical documents have three major components. These components are placed in the document in the order shown in Table 1.
Table 1
Major parts of a simple document
Component Subdivision Front matter Title page Contents Using this book (Preface) Acknowledgments Text Sections and subsections Appendices Back matter Bibliography Glossary
Major divisions within a simple document are called sections and appendices. Major divisions within a section or appendix are called 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.
There should be a shortened version of the copyright notice on the title page in lieu of having a specific copyright page. At a minimum the copyright notice on the title page must include the following:
The copyright notice on the title page should be in the footer.
"Contents" is the next component in a simple technical document. Headers, footers, and page numbers first appear here, in lowercase Roman numerals, even though page counting begins with the title page.
"Contents" lists the preface 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 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, the section and subsection numbers (which are optional and may be used at the writer's discretion) 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.
Do not use the word "Table" in the table of contents title. Simply call it "Contents."
This front matter section is named "Preface" in simple technical. It usually contains the following information in this order:
The preface is the first section or chapter listed on the Contents page.
The preface can be omitted in simple technical documents.
The text of a proposal or results document contains the following three major components:
Sections are used only in proposals and results documents.
A section contains a section title, an introductory paragraph, and up to 3 levels of text. As a general guideline, try to keep sections as short as possible and address only one major topic in each section.
Section titles should be short and describe the section contents succinctly. Section titles should be task-oriented; starting the title with words like Working, Using, Maintaining, and other similar concepts is strongly recommended.
After the section title and before any subsidiary-level heading (Heading 1, Heading 2, Heading 3), there can be a brief overview or introductory paragraph that describes the intents and contents of the section.
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. If there is a section 1.1 there must be a 1.2. Likewise if there is a section 1.2.1 there must be a 1.2.2. 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 numbered or not numbered at the discretion of the author. If headings and subheadings are numbered, the number is separated from the heading text by an em space. First-level headings (Heading 1) should have numbers in the format s.1, s.2, s.3, and so on. Second-level headings (Heading 2) should have numbers in the format s.t.1, s.t.2, and so on. Third-level headings (Heading 3) should have numbers in the format s.t.u.1, s.t.u.2, and so on. Fourth-level headings (Heading 4) should be discouraged.
An appendix(1) 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.
Back matter includes the following:(1)
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 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.
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 simple technical documents the 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. Figure 1 provides a sample footer for single-sided documents.
Figure 1
Footer for simple 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.(2) Collective Technologies uses footnotes, not endnotes, for references in most documents. In white papers or conference papers, endnotes may be used at the author's discretion.
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.(3)
Footnotes in tables and figures use alphabetic letters (a, b, c) as their reference markers.
In simple technical documents the page header contains the document title, above a 2-point horizontal rule, in Arial Black 11-point text. A sample header is in Figure 2.
Figure 2
Header for simple documents
Document Title
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 numbered or not numbered at the discretion of the writer. If headings and subheadings are numbered, the number is separated from the heading text by an em space. First-level headings (Heading 1) should have numbers in the format s.1, s.2, s.3, and so on. Second-level headings (Heading 2) should have numbers in the format s.t.1, s.t.2, and so on. Third-level headings (Heading 3) should have numbers in the format s.t.u.1, s.t.u.2, and so on. Fourth-level headings (Heading 4) should be discouraged.
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 document -- title page, contents, major numbered sections, appendices, bibliographies, and glossaries -- should always start on their own pages.
Within appendices and sections, 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.
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 except the title page should have a page number.
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 Section 1 (on page 1). Appendices, bibliographies, and glossaries are numbered in the same manner as major sections.
The first page of an appendix or section looks like the following:
The first page of a special section -- Contents, Bibliography, or Glossary -- 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 (Contents, Bibliography, or Glossary). 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.
Body pages in a simple technical document look like the following:
![[Contents]](/icons/buttons/toc.gif){kind=icon}
Jump to table of contents
![[Back]](/icons/buttons/previous.gif){kind=icon}
Back to "Using this book"
![[Next]](/icons/buttons/next.gif){kind=icon}
Onward to Chapter 2, "Complex technical document structure"
![[Note]](/icons/buttons/lightbulb.gif){kind=icon}