Style Guide

The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Introduction Pages

As editors, we maintain the quality of the platform. All editors are encouraged to make edits and revisions so that pages adhere to this style guide, which supports:

Predictability - A reader knows what to expect and can find information easily.
Efficient Production - A writer following conventions can rapidly produce content.
Organized Knowledge - A shared standard for compartmentalized knowledge reduces redundancy, eases updates, and improves cross-referencing.

We develop concise collections of evidence. We don't use page content to tell long stories. If we want to tell a story, we publish our own documents as a PDF and add it to the collection. To become an strong editor, consider learning how to Edit Source Wiki Markup Code, in addition to the following guidance:

Keep To One Subject Per Page

We aim for each page to curate evidence, ideas and questions on a single subject. We develop a coherent constellation of knowledge about workgroups and their efforts across places and topics by linking among pages.

Adhere to Page Type - Page type constrains page content to information about a Place, a Workgroup, a Topic, an Effort, or a Product. Be sure to search for your topic before creating a new page.
Pick Title and Categories Carefully - Once defining page type we use only the best categories to define a page. A page that collects information about beach spawning on beaches by forage fish might use the category "Beach" and "Forage Fish" and "Life History". Once you define page type, a title, and categories, stick to your subject. Don't wander.
Organize Content from Pattern to Detail - Within a page or within a page section, provide general overview information first. Organize details as they accumulate.
Don’t Ramble; Link To Relevant Pages - If there is a related topic, use a link rather than restating content on other pages.
Use Standard Page Sections - Presenting page content within standard text blocks makes pages predictable and thus easy to access.

Use High Level Pages to Organize Low Level Pages

Our Categories suggest a hierarchy of information. We maintain a set of pages associated with categories for the purpose of organizing all content associated with that category. The purpose of the Salmon page is to organize all pages using the Category:Salmon.

Dynamic Page Lists - Use DPL queries to generate lists of pages. Use more precise queries to curate the page content. For example, if we have lots of salmon pages that also use the category restoration, then create a special section for that
Formatting Templates - When presenting a large number of DPL queries, consider using our {{TwoColumn}} or {{ThreeColumn}} templates to present information densely on the page.

Use Standard Page Sections

A page is made of sections. Each section (except the blurb) begin with a level 2 Heading followed by no more than a few sentences of plain text describing what you will find in the section, followed by bulleted content. Level 1 headings are reserved for special circumstances. Level 3 headings are reserved for subdivisions within long sections.

The Blurb - The blurb is a paragraph in bold face font that describes the subject of the page, and its relationship to other workgroups, places and topics. It optimizes the use of in-line links to relate the current page to other pages, and thereby reducing the need for redundant information.
Links - often near the top of a page you might provide a set of general links to key websites about a Workgroup, Effort, or Product. Providing the actual HTTP address provides useful information
Notes - A minimalist page may have just a title, categories, a blurb and a notes section. Notes include a bulleted set of observations, facts, citations or opinions. As the notes section develops this may suggests the need for additional sections.
Chronology - Often a wide range of different efforts by many workgroups tell the story of a place. One way to tell this story is with a simple clean chronology. These often describe trans-institutional knowledge available nowhere else (see Snohomish Delta#Chronology.
Questions - Distinct from notes a passing editor may leave questions in a question section. This indicates where additional research on a topic may be useful.
Dynamic Page Lists - Some pages are associated with categories, or consider the intersection of several categories. A dynamic page list can automatically generate a list of links based on the intersection of several categories, creating a table of contents that links to other pages.

Capitalize Links and Page Names

Because wiki page names are case-sensitive, we have particular conventions about capitalization. Both page names are Categories are capitalized as titles. When linking to a page name in the flow of text, we generally use the capitalized page name.

Create Good Blurbs

A critical component of most pages is an initial blurb, presented in a bold font that introduces the page and its relationship with other pages. Within a blurb think like a newspaper editor and answer what, where, why, how and when as appropriate. A blurb should generally be less that 250 words, preferably in one, or at most two paragraphs. Blurbs should generally work from larger scales to smaller scales, and from ecological assessment to socio-economic assessment. Language should be very short, and designed to demonstrate how the page relates to other pages. Save details for the content. The blurb should maximize the use of In-Line Page Linking (see below).

Favor Bulleted Lists Within Sections

Except for The Blurb and standard section introduction, most page content takes the form of bulleted lists. If you would like to contribute long-form prose to the site, please author and publish an article or memo as a Product and cite it in a bulleted list. We drive content into bulleted lists because they encourage:

Reordering as part of page revision.
Brief language better suited to information exchange.
The addition of new points or sub-points of information by other authors.
More precise citation of each point of information.

Avoid Redundancy--Use Links To Point At Other Pages

We have conventions for how we place links so they are clear and predictable.

Link Capitalization - All links and categories should be capitalized as titles, even when used in-line.
Links As Sentence Subjects - A link may be used in whole and then described in the following sentence. In the case of more complex product names, a short citation is preferred (see below).
Off-Site Links - Be judicious in the use of off-site links. They change frequently. Instead, reference Workgroup pages, which are easier to update.

Format Bulleted Lists For Easy Skimming

We make bulleted lists more legible a bullet may be followed by a label, separated by test using a hyphen.

Bold Labels - In general labels use bold font and are capitalized as if a title.
ALL CAPITAL Labels - You may use all-caps font to draw attention to a particularly important label, however the practice should be reserved for special occasions.
Date Labels - Particularly with Chronologies, list entry can start with a bold date. Years are presented as four-digit integers, or to increase precision while accentuating year, using a convention starting with four-digit year, abbreviated month and a two digit day, such as "2000 Jan 01".

Use Sections to Answer Questions Consistent With Page Type

Context structure follows recurring patterns to organize information related to page type. Some page types are managed as high-level organizing pages, and these pages have complex formatting and present many pages through a series of queries and links.

Questions have a special role on the platform. In fact there is almost no arena of life where formulating carefully considered questions is not useful. Lots of answers in the absence of questions creates clutter. Good questions, help develop useful answers.

Efforts

Effort pages are often to short in duration to merit a chronology. Efforts are usually described by categories, and do not support DPL or Category Tree queries.

The Blurb - The blurb generally identifies "who did what where and when and for what purpose"
Links - For efforts that have specific high value pages you might include a clear link. In most cases, links can just be provided in the notes, given that most projects may be referenced by several sites: sponsor promotional sites, agency contract database reports, project partner mentions, news articles, etc.
Notes - Notes are the core section describing nuances of the effort, lessons learned, and related topics. Avoid long descriptions of methods, instead linking to and contributing to topic pages. For example, consider contributing to the Topic Page Engineered Log Jams, rather than providing general information on an effort page.

Workgroups

Workgroup pages are not written to promote institutions, but to describe them in practical terms as part of a social-ecological system. Stick to the facts. First describe durable structures and processes, rather then more transient behaviors (although documenting behaviors is also useful). The Blurb is focused and a link is usually provided. Chronology might be useful, and where efforts and products have been flagged by a category, they can be shown on a workgroup page using a DPL.

The Blurb - Describe the purposes of the institution, the position of the institution in power structures and hierarchies and its governance, the location of offices, the general number of staff, and the source of revenue. Important legal authorities may be mentioned, but are detailed in the notes.
Links - A link to the main webpage is usually provided. Institutional website change all the time, and so more detailed links may have limited value. If the institution has a stable archive, that could be useful.
Notes - A notes section is often quickly subdivided to describe the various programs within an institution that are most relevant to social-ecological work. This requires some discrimination about what qualities of an institution should be described. This is where efforts and phenomena can be explored.
Chronology - Sometimes a chronology of the history of an institution is useful and instructive. Often historical landmarks are not presented by institutions that prefer to focus on present situations.
Dynamic Page Lists - Typically an institution will use an acronym (see Category:Acronym to flag efforts or even places upon which they are focused. This collection of flagged pages can be automatically reproduced on the Workgroup Page using DPL.

Products

Products are often short descriptions, by readers wanting to remember something important in a document. Typically a blurb/citation, link and notes are sufficient

The Blurb/Citation - Instead of a blurb we typically use a bibliographic citation, usually using APA format. You can quickly extract a citation using Google Scholar, and finding the cite link.
Links - A product page should have a direct link (to the actual file) either to the resource on the wiki or to a stable location off-wiki.
Notes - Notes often summarize key claims in a document, and might provide a page number for convenience.
Dynamic Page Lists - although not typical, a DPL query could use product categories to generate a list of "related documents."

Topics

Topic pages have the most complicated category hierarchy of all page types. High-level topic pages gather and represent links to underlying topic pages. A links section is uncommon. Usually notes present points of information, and then become subdivided as they accumulate. Some topics lend themselves to chronologies. Many topics are clearly associated with one or more topics

The Blurb - Foremost, define how the topic is related to other topics, either larger, smaller, or adjacent. Identify places where the topic is important. If a topic is dominated by a particular workgroup or effort, it might be worth mentioning--usually not.
Notes -
Dynamic Page Lists - Topic pages are organized into hierarchies. High level topics often summarize a category, while mid-level topics may describe the intersection of several categories. For these pages, related topics or sub-topics are best represented using DPLs.

Places

New editors are likely to focus on Landforms or Sites. Pages about Regions use lots of DPLs and general information about important topics. Most Catchment Scale places are similar, in that they may initially map and introduce the landscape generally, however more often some key products or efforts can be identified that provide an overview. Pages about Landforms begin to describe

The Blurb - Describe the relationship between the place and surrounding and adjacent places. Where possible describe area and population. Describe the dominant geological and ecological features including elevation. Describe the relationships between the place and governments, particularly Counties, Tribal Governments, and Municipalities.
Notes - Not unlike topics the bulk of a place page starts with points of information that are then organized organically into subsections. For places notes may include ecological and socioeconomic branches.
Chronology - Chronologies of places are frequently lost, and the domain of local historians. Capturing the history of a place is a service.
Dynamic Page Lists - For places where there is an accumulation of efforts and products, a category for that place becomes important, and then, a DPL can be used to point to all pages related to a place.