Page Formatting Guidelines

Guidelines are suggestions. They are not rules.¹

Top of Page

Titles
- Use h1 tags.
- Each help page should have a title.²
Subtitles
- Use h2 tags.
"Under Construction" Warning
- Alert the reader that the page is under construction.
- Warn other help page editors not to make changes.
- Use the Under Construction template.
"Major Update" Warning
- The Major Update template links to the sandbox where the update is under construction.
- There is a companion template for the sandbox. It links back to the source page.
Table of Contents
- Use the Table of Contents template.
- Use the #link naming conventions.
- Precede subsection titles by three periods (...) and use a slightly smaller font to set them apart from the section titles. Use initial caps for the section titles.
- If there is any doubt about the need for the TOC, put it in. The TOC provides
  - a map of he page layout
  - one-click navigation
  - the URL of items on the help page

Middle of Page

Section Titles
- Use h4 tags.
  - The first section in the Main KGS Window help page is an exception to this rule. It uses h3 tags to set it off from the following sections.
  - Two ways to make the section titles stand out from the rest of the text:
    1. Number them.
    2. Indent the text using the CSS "relative positioning" capability.
    The Tips and Tricks page combines both of these techniques to make the section titles stand out even more.
Subsections
- One way to make subsections is to use nested lists. This method is used on this help page. The top level list item is a subsection title. For example, the title of this subsection is "Subsections".
- This page uses <big>, </big> tags to make the subsection titles stand out.
- The CSS "relative positioning" property can also be used to set the subsections apart from the sections. This is done on the CGoban Main Window help page.
Links
- Use bidirectional links when appropriate.
  - Example: The "silver crown" link between the Tournament FAQ page and the Icon page is a bidirectional link.
- Use the #link naming conventions for links to the interior of a page.
Tips and Tricks
- Helpful for miscellaneous things that do not fit naturally in the other sections.
  - Especially useful for presenting relevant information on a FAQ page that does not fit into the Q and A format.
  - The Writing Style Guidelines have a Tips and Tricks section.

Bottom of Page

Footnotes
- Footnotes go immediately after the main text of the page.
Glossary
- Definitions and acronyms
References
- References to source material for items on the page.
  - Example: Chat Line Etiquette help page
Related Links
- Links found elsewhere on the page may be included in this list.
- Include a link to the next higher page in the help page hierarchy, especially if the help page is not listed in the Hot Links.
  - In other words, a link back to the primary page that links to the current page.
  - This is not necessary for short pages that do not have a "Related Links" section.
Endnotes
- Endnotes go right before the link to the top of the page.
Top of Page
- A link from the bottom of the page to the top of the page.
- If there are change notes, then, this link goes right before the change-note horizontal line.
- Template for the title: <a name="topofpage"> The title of your page goes here. </a>
- Template for the bottom: <a href="#topofpage">Top</a>

Change Notes

Change notes often appear at the very bottom of the page. Minor change notes (such as "link needed") appear where the change needs to be made.

Purpose
- Suggest updates to the page.
- Remind you of changes you want to make.
- Warn the reader that the page content might be out-of-date, inaccurate, or confusing in some way.
Format
- Enclose in parentheses and put in italics.
- Include your user name or initials.
- Include a date. Date format: month/year.
 Example: (This is an example of a signed change note. glue 4/2010)
 Template: (text user-name, date)
- Put a horizontal line (<hr>) (or lines) before change note section.
Updating Change Notes
- Delete implemented notes.
- Delete notes that are no longer relevant.
  - If a suggestion has not been implemented in ten years, it is not likely to be implemented any time soon.
- Annotate notes that need clarification.
  - Example: (This is an example of an annotated change note. glue 4/2010. This is the annotation. dj 9/2010.)
- There are a lot of change notes in Future Editing Plans.

Rule of Seven

Avoid lists of more than seven items.
Use nested lists.
- Example: The ten items in the "Change Notes" section are divided into three groups.
Demote sections to subsections.
- Example: The use of nested ordered lists to create subsections in the Coding Styles page.
Use subtitles to cluster similar sections.
- Example: Subtitles are used to cluster the sections in the Editor's Help Page.

end of the page formatting guidelines

Footnotes

¹ Page formatting guidelines give the help pages a uniform look and feel, making the pages easier to understand.

The listed page elements are all optional except for the title. The order in which they occur is also important. For example, putting a Major Update warning before the Table of Contents makes it easier to release intermediate drafts. Just copy the text in the sandbox from the TOC on down, and the Major Update warning in the source file is left unchanged.

² The title is an essential part of each help page. As a user navigates through the help pages, it is easy to become confused as to where they are. This is especially true for newbies. After all, a newbie is not familiar with the hierarchical structure of the KGS help page network. Having a title at the top of the page lets the user know where they are in the help page hierarchy.

It is also important to use the same format (i.d., h1 tags) for the title if possible. This keeps the title from "jumping around" as much when the user is quickly navigating through the pages. For example, a user (especially a newbie) might be clicking on the links in the Hot Links box one after the other just to get a feel for what the references pages look like.

Glossary

Help Page Elements
- All of the subsection titles on this page are "help page elements". For example, the "Title" is a "help page element", and so are the "Endnotes".