SEAMONSTER Wiki Structure

From Seamonster
Jump to: navigation, search

Introduction

This meta-page describes wiki page formatting. If you are interested in creating pages we hope you might (and encourage you to) internalize this material as a starting point.


The SEAMONSTER wiki must accommodate three "classes" of visitor:

  • Surfers: People who want to scan the site/project quickly
  • Divers: People in search of deeper detailed information
  • Monsters: SEAMONSTER project members.


The pages we place here are also categorized by depth:


  • Primary: Main pages and single-click pages: Basics, overviews.
  • Secondary: Two clicks from the main page: Getting technical.
  • Tertiary: Three+ clicks from the main page: Can be very technical
  • Notes: Page titles begin with '20' (as in 2008_10_12_Robs_Notes_on_TOS2_Mote_programming): Used to hold temporary information.


Notes pages may eventually become annals pages in a suitable section (where they wouldn't be considered temporary). However in order to regularize listings of pages we would use a category word 'Annals' at the beginning of the page name to keep them all together.


Related material


Simple Formatting Tricks

Mendenhall Glacier outflow river, dubbed 'Little Niagara', August 2008
  • Upload an image, insert it into a page
    • Use the toolbox 'Upload file' link to upload an image
      • Try to keep the image size < 250kb if possible
    • Notice the glacier image shown here is right-justified and has a mouse-over caption.
      • Click on the edit or source tab at the top of this page to see how to do this.


  • In general you will save time by finding the formatting you want and just looking at the source page.


  • Section headings
    • We tend not to use = Major Header = format much
    • Divide a page into sections using == Secondary Header == format
    • Break that into === Tertiary === Sections
    • And ==== Quaternary ==== necessary
    • But if the page is getting pretty big: Consider breaking it into multiple smaller pages


Content

General concept

Wikis by design tend to drive content towards consent. If you disagree with what I write, you edit the page and represent your views. We iterate until consent is reached (even if it is a more careful statement of the disagreement.) For a small project like SEAMONSTER we can also iterate directly by phone or in person or by email.


Wikis "proceed" as dynamic entities usually without much in the way of formal ontology (agreement on meaning, rules for presentation of ideas, claims, hypotheses, etc). There are at least two good reasons for this: First, we generally communicate informally without too much trouble understanding one another. Second, organizing information is hard work. In order to import content to the wiki we generally encourage contributors to write "something! anything! since disorganized anything is considered of greater value than highly organized nothing.


However we also suggest (to ourselves) that there is potential for migration, towards a consistent ontology that depends heavily on time spent reviewing and organizing wiki content. This is important in a unifying sense as related semantics are needed in building the project relational database.


Imagine, then, that there are two types of wiki content

  • polished text: Oriented towards Surfers and Divers
  • raw material: Notes for Monsters


SEAMONSTER wiki page types by depth category

  • Templates (how to make them: See below) are used as directories. They are included at the top of all the pages they list. This group of pages should be related by a common theme such as 'network' or 'science'. A template may include Primary, Secondary, Tertiary, and Scratch (20X) pages in its listing.
  • Primary pages are the Main Page and pages directly referenced by it. It is permitted but strongly discouraged to have a pile of Notes at the bottom of a Primary page. Notes sections are more common on Secondary and Tertiary pages. They are set off using a single Equal Sign as in "= Notes =".
  • Secondary pages are listed in maps (templates) like seamonster:map_environment. They may also carry Notes sections at the bottom, in fact this is a welcome practice for unsorted but important material.
  • Tertiary pages are neither primary nor secondary. They are used to keep the size of secondary pages down and carry their own local page link directory at the top. Idea is this: You are writing a secondary page on diatoms, you need a digression on calcium carbonate accretion, and so you set up the link on the diatom page. At the top of the CaCO3 page you put a link back to the diatoms. Later you link to the CaCO3 page from another page on Invertebrates so: Of course you put a link back to Invertebrates at the top of the CaCO3 page. Easy! As with primary and secondary pages you are permitted to keep a Notes section at the bottom.
  • 20X or Scratch pages should begin with the digits 20 and this is generally a date, year first, followed by a descriptive title. They can contain anything but are usually created as notes / logs.


Page types by visitor category

Wiki for Surfers

The Main Page and all Single-Link pages from it should be large font, heavy on pictures/images, light on text.


Wiki for Divers

The Main Page has to provide enough of a diving platform [sic] so that the Diver has an idea of what might be found. Then ideally we want the Diver to be able to dive down without cracking their head on a shallow (empty) page. This in combo with Ideas for Surfers unfortunately implies that pages aren't really going to get technical until that second click. First click from the Main Page goes to a Subject Master page and the second click goes to technical content. As a rule of thumb.


Wiki for Monsters

First rule of the wiki: Always write in the wiki. (Even if said writing is always raw: Doesn't matter. Always good to write in the wiki.)


Creating New Pages

  • Near the top of the tree (Main, One Click, Two Clicks): Choose a page title consisting of one, two, or (max) three words.
  • Start every page with an Introduction section of one or two short, concise paragraphs.
  • To go to Diver depth (second tier) can often simply add "Title: Subtitle" pages as needed.
  • This can be recursed to SubSubTitles of course


Creating a subtopic directory using a template

A template is a wiki page that can be embedded in other wiki pages. This avoids having to replicate content in multiple places. The first use of templates is to facilitate wiki navigation.


We have collections of related wiki pages, for example on the subtopic of Motes. To make navigating across these pages easier create a template page by typing this text into one of the pages:


{{seamonster:map_<subtopic>}}


Save this page and click on the resulting link to create the template page. This page can contain a series of links to all the related subtopic pages. Visit each of these pages in turn and include the template link as a above.


To edit a template: Go to any page that contains it, click on its edit hypertext (easy!). If you edit the entire page (top tab) that contains the template, the template is also listed at the bottom as a link, can be reached and edited that way.

Page Formatting

Again, near the Main Page we want brevity so keep the length of each page short, perhaps no longer than three browser pages worth of scrolling. Divers and Monsters may arrive at long long pages (code printouts, journals etc). These should at least be broken up in sections to facilitate links and editing. Again these are just suggestions, not iron clad rules.


Finally visuals always win. Diagrams, photos, anything visual, upload them and insert them to break up the text of these pages. This page violates this rule but that's because it is a metapage.


Terminology

Rob started using Web Portal or Portal to mean something a human interacts with and Web Service to mean something a computer interacts with. Adopt! Or talk me out of it.