----
h1. caGrid Notation Standards
----
{cagridtoc:exclude=caGrid Notation Standards}{cagridtoc}

The following is general notation standards that all pages on caGrid.org should use. These standards create congruence throughout the site. We ask that if you are creating or modify any pages on the caGrid.org site, you read through and follow these standards so that your pages will flow with the other pages.

h1. Headings and Table of Contents
----
h2. Page Titles

All pages on caGrid.org should have a page title. A page break should at least be after the first heading/title (h1.) and can also be after the page title if appropriate. For example in wiki markup:
{noformat}
----
h1. caGrid Notation Standards
----
{noformat}
This produces the page title that you can see on this page before the table of contents.

h2. Table of Contents
----
Most pages on cagrid.org should have a table of contents. Place a table of contents immediately after the page title and before any text or headings. To use the caGrid table of contents, use the following macro after your pages title heading. You should exclude the page title from the table of contents by setting the exclude parameter.

{cagridtable}
{table-row}
{th:class=confluenceTh|colspan=1}*Notation*{th}
{th:class=confluenceTh|colspan=1}*Example*{th}
{table-row}
{table-row}
{cagridtablecell}
{noformat}
{cagridtoc:exclude=caGrid Notation Standards}
{noformat}
{cagridtablecell}
{cagridtablecell}
{cagridtoc:exclude=caGrid Notation Standards}
{cagridtablecell}
{table-row}
{cagridtable}

h2. Page Breaks
----
Page breaks should be used after "h1." headings and/or "h2." headings depending on the context and layout of the page. For example:
{noformat}
h1. Title
----
Here is a basic introduction a paragraph long.....
...
...
...
...
h2. Sub-Title
----
Notice that there is a page break (----) after the h1. title and h2. title...
{noformat}
If you have a "h2." heading immediately after a "h1." heading, only put a page break after the h1. heading. For example:
{noformat}
h1. Headings and Table of Contents
----
h2. Page Titles

All pages on caGrid.org should have...
{noformat}

You can see this format above.

Page breaks make it easier for readers to identify sections within the page. For long pages, there should be page breaks between main sections. For guides, tutorials, or pages with in-depth explanations, it is best to a have a clearly defined outline of the page and/or steps. This includes using various heading sizes to indicated content sections or steps and sub-sections or break down of steps.

h1. Text Formatting
----
caGrid wiki standards use *bold* for text when referring to specific directories, buttons, or actions (directions in tutorials). *Do not use* _italics_ or +underline+.

h1. Images
----

When displaying an image, caGrid notation standards ask that you use \{gallery}, even when only displaying one image. This makes the images smaller, yet when clicked, expands into a larger image without going to a different page. The \{gallery} should be used for most images.

The only time \!image.png! should be used, is when the image is small enough so that it doesn't interfere with the flow of the page or the text of the page specifically refers to something in the image. See the image in the "Tutorials" section below for an example.

h1. Tutorials
----
Tutorials usually have a step-by-step process that should be broken up to separate pages so that the steps are easily identified and so that a single page is not overwhelmingly long. If you are putting a tutorial on caGrid, create children pages for the sections of the tutorial as you see fit. These should be children pages under the tutorial parent page. For example look at the following tutorial page tree:
!Tutorial Tree.PNG|align=center!

Here you can see the parent page "Develop a caGri Data Service Supporting caCORE SDK 4.1.1". Each phase of the tutorial is separate child page underneath. Notice how the phases are in the proper numerical order. This is important for the \{scrollbar} feature that is used for tutorials. When creating pages for steps or phases, make sure they are listed in correct order. To move the location of a page, *Edit* the page and then edit the *Location* (near the bottom of the edit page screen). Or, you can view the *site map* of the space that the tutorial is in and click and drag the pages so that they are in the correct order.

Once you have your parent page and children pages in order, you can use the \{scrollbar} feature to provide easy navigation between the pages/steps. Insert \{scrollbar} at the top or bottom of a page. This places arrows on the page which allow the reader to navigate to the next page or previous page in the hierarchy. An "up" arrow is also inserted to allow the user to navigate to the parent tutorial page.

See [cagrid13tutorials:Develop a caGrid Data Service Supporting caCORE SDK 4.1.1] for an example.

h1. General
----

Other general notation standards to make pages look their best: