A Visual Guide to
Document Design and Layout

Technical writing departments in their infancy seem to have great difficulty producing documentation that is well designed and consistent in appearance throughout all documents. As the department matures, it attempts to "consistify" the format of the documentation, but, unless there is an experienced template designer on board, this is often a drawn-out process involving focus groups and much squabbling. Once the format or template is complete, however, an interesting phenomenon may be observed, which is that one company's well formatted templates tend to be nearly identical to the well formatted templates designed by every other technical writing department in the world. Aside from a handful of design features that distinguish the look and feel of one company's documentation from that of its competitors, everything else is pretty much the same. Whether a focus group spends six months or two years designing templates, they all discover that a well formatted user guide contains some specific and standard design elements, which are described in the table below.

Speaking of layouts, the layout of this article did not turn out as well as I thought it would. I am going to think of some other visually appealing ways of presenting this information; in the meantime, please excuse the long, narrow columns!

Note: The graphics below are not thumbnails; they will not become "full-sized" if you double-click on them.

Left-Hand (Verso) PageSample Two-Page SpreadRight-Hand (Recto) Page

Cover Page
The cover page is unnumbered and contains the title of the document in large type. There are many ways to write the title; you can look at published books for ideas.

The cover page also contains the corporate logo and perhaps a graphic. It might also contain the document number, but some writers prefer to put this on the title page.

Inside Front Cover
The inside front cover is blank.

Title Page
The title page is the first page (page i) of the document, although it is unnumbered. It contains the full title of the document as well as the document number and the revision number. There is no header or footer on this page.

Rather than manually typing the title, it is a good idea to create a cross-reference to the information on the cover page. This way, if the document title changes during the project (and titles do tend to change), you will have to change only the cover page: the title page will be automatically updated with the new information.

Copyright Page
The verso of the title page contains copyright information for the document and for all the products mentioned within the document, whether they are third-party products or proprietary to your company. This page is unnumbered and does not contain a header or footer.

For more information about writing copyrights, see Writing Copyrights.

Publication History
The publication history page describes, in point form, the changes you made to the document in this release. This page is not essential, but it allows you to avoid the use of distracting and cryptic revision bars in your document. The publication history contains the document issue date and the document version followed by a list of the changes made to the document since the last version. For example:
Rev. C, October 2003
  • Added "Conformance" chapter.
  • Deleted ACTIVATE from the Actions section of BACKUP.
  • Made minor editorial corrections throughout.
    Rev. B, June 2003
  • Added "Errors and Notifications" chapter.
  • Made minor editorial corrections throughout.
    Rev. A, January 2003
    First release of this document
  • Continuation of publication history, or blank
    The publication history can extend to the next page or to as many pages as required. In the example here, the publication history fitted on the first page and so this page is blank.

    Table of Contents
    The table of contents (TOC) always begins on a right-hand page. The first page of the TOC contains a footer, but no header. If the TOC continues onto a second (or third) page, these pages should contain headers as well as footers.

    The TOC is the first page in the document to display a page number, but this is not page 1 or even page i. To determine the correct page number, count the number of pages (including blank pages), starting at the title page. If the result is an even number, you have mis-counted. All right-hand pages have an odd page number and since the TOC is on a right-hand page, it must have an odd page number too.

    Since the TOC is part of the frontmatter of the document, its page numbers are formatted as Roman numerals. So, counting from the title page and assuming that your document contains the same number of pages as the graphical examples in this article, the TOC would begin on page v. If you don't have a publication history in your document, the TOC will most likely begin on page iii.

    The page number can be placed in either the header or the footer, but I think it is easier for people to find when it is in the footer. Also, I prefer to put the number in the outside corner of the footer rather than in the middle because it is easier to find when flipping through pages. Some writers put the number in the footer of the first page, and in the headers of the remaining pages.

    The correct name for a page number is folio. If the folio appears at the bottom of the page, it is called a drop folio. If the folio does not appear on a page that is counted (such as the title page), it is called a blind folio.

    A TOC in a user guide often includes a list of tables and a list of illustrations.

    Continuation of TOC
    The verso of the TOC contains headers and footers, even if the TOC itself does not extend onto this page.

    Introduction
    The introduction begins on a right-hand page and contains a footer, but no header.

    Since user guides are often restricted to people with a specific kind of expertise, and since they often make use of formatting conventions that might otherwise be cryptic, the purpose of the introduction is to describe who may use the document and, only if absolutely necessary, how to understand the formatting conventions. If the document belongs to a suite of documents, it is a good idea to name all of these documents and provide a short description of them. If the document refers to other documents, it is also a good idea to list them here so that users can get copies to have at hand at the appropriate time.

    Since the introduction is part of the frontmatter, its page numbers are Roman numerals.

    Continuation of Introduction
    The verso of the introduction contains headers and footers, even if the introduction itself does not extend onto this page.

    First Page of Chapter
    The first page of a chapter begins on a right-hand page and contains a footer, but no header. Chapter pages are numbered in Arabic numerals, starting at page 1.
    Left-Hand Page of Chapter
    Notice that the left-hand page of the chapter has a different appearance from the first page of the chapter. The first page of a chapter is a "display" page, as is the first page of the introduction, and therefore does not contain a header. However, all subsequent pages of the chapter must contain a header and a footer.

    Right-Hand Page of Chapter
    The right-hand page of a chapter has a similar appearance to the second, except that the page numbers are positioned so that they mirror each other.
    Continuation of Chapter
    The last page of a chapter contains headers and footers, even if the text of the chapter does not extend onto this page.

    Appendix
    The appendix begins on a right-hand page and contains a footer, but no header. It is numbered with Arabic numerals continuing sequentially from the previous section. While the title should indicate that this section is an appendix (e.g., "Appendix", "Appendix 1" or "Appendix A"), do not use the page numbering format wherein page numbers restart at each new appendix and are preceded by the appendix number or letter (e.g., A-1) because this format makes it difficult for the user to find a particular page.

    An appendix contains data, elaborations, or explanations that are not essential, but that might be helpful to the user. In technical documentation, however, it is better to avoid using appendices.

    Continuation of Chapter or Appendix
    The last page of a chapter contains headers and footers, even if the text of the chapter does not extend onto this page.

    Glossary
    The glossary begins on a right-hand page and contains a footer, but no header. It is numbered with Arabic numerals continuing sequentially from the previous section.

    For more information about glossaries, see Writing Glossaries.

    Continuation of Glossary
    The last page of the glossary contains headers and footers, even if the text of the glossary does not extend onto this page.

    Index
    The index begins on a right-hand page and contains a footer, but no header. It is numbered with Arabic numerals continuing sequentially from the previous section. It is customary to set the index in two columns and to use a smaller type size.
    Continuation of Index
    The last page of the index contains headers and footers, even if the text of the index does not extend onto this page.

    Inside Back Cover
    This page is completely blank.
    Back Cover
    The back cover does not contain a header and footer. In fact, the back cover can be completely blank, but I like it to contain the company logo, the title of the document, the document number, and the version number.

    Google
    Webwww.docsymmetry.com