This page
Other pages
Account
Administration
caGrid Notation Standards
 |
 |
 |
 |
Contents |
 |
 |
 |
 |
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.
Headings and Table of Contents
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:
---- h1. caGrid Notation Standards ----
This produces the page title that you can see on this page before the table of contents.
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.
| Notation | Example | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
{cagridtoc:exclude=caGrid Notation Standards}
|
|
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:
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...
If you have a "h2." heading immediately after a "h1." heading, only put a page break after the h1. heading. For example:
h1. Headings and Table of Contents ---- h2. Page Titles All pages on caGrid.org should have...
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.
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.
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 directly being referred to in the text of the page. For example it should only be used when the page says, "Look at the image below.".
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:
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).
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 Develop a caGrid Data Service Supporting caCORE SDK 4.1.1 for an example.
General
Other general notation standards to make pages look their best:
- Use sections and columns when walking through steps or explanations that directly correspond to images. In left column should be the text and in the right should be the corresponding images. See the following pages for an example: Advanced - Photosharing Operations and Understanding the Boot Camp data model
- Color Palette compatible with our site: http://www.colourlovers.com/palette/319506/behaviour
