Style Guide

Introduction Pages[edit]

See Technical Pages

The platform is more cartography than exposition. Contributing to the platform requires the discipline to provide useful information with the least clutter. If everyone adds surplus text, the platform becomes a morass. Each page contains one carefully scraped lump of information defined by Page Type and Categories. Together we are building a map, using a minimum of symbols.

Our content is about ecosystem stewardship; we explore the interface between our human social, cultural, and economic systems and the condition of the earth. Don't wander out of this territory.

We have a shared style guide so we can write in a way that encourages to contribution of others. Keep language simple. Avoid long sentences. We mostly use bullets. If we want to tell a narrative in paragraphs, then we author and publish our own documents and add them to the collection. Please don't reproduce your documents on wiki pages. This journalistic style encourages:

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

Create An Editor Account[edit]

Page Creation[edit]

Each new page is part of a mosaic of pages. When inserting a new page, consciously add depth or breadth to an existing set of pages. Therefor research existing platform content before you create a new page.

One Subject Per Page[edit]

We avoid creating content that overlaps unnecessarily with other pages. We instead build a network of knowledge by linking among pages.

Adhere to Page Type - Page Type constrains page content to information about either a Place, a Workgroup, a Topic, an Effort, or a Product. If you are explaining an effort, don't explain a topic, just link to the apporpriate topic page.
Pick Page Title and Categories Carefully - Use a limited set of the best categories to define a page. The goal is to NOT click all the category boxes. 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. Most pages organize evidence at the intersection of one to at most four or five categories. For example the page River Delta Restoration presents information at the intersection of Category:River Delta and Category:Restoration. River Delta Restoration Monitoring adds depth by adding a third category.
Organize Content from Pattern to Detail - Within a page or within a page section, provide general overview information first in a "blurb" (see below). Organize details as they accumulate.
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[edit]

Our Categories propse 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.

Architecture and Content Pages
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.
Content Templates - We have standard templates that let you rapidly present various types of pages associated with one or more categories.

Use Standard Page Sections[edit]

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[edit]

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[edit]

Most pages begin with a blurb in bold font that introduces the page and its relationships to 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 broader ideas to more specific, from ecological to social-economic. Be short, and use links. Save details for the content. If a page is very closely related to other pagees, consider using an "Also see..." preamble to indicate those related pages (for example see Categories which is closely related to Platform Architecture.

Use Bulleted Lists Within Sections[edit]

Except for The Blurb and standard section introduction, most page content best 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.

Format Bulleted Lists For Easy Skimming[edit]

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".

Avoid Redundancy--Use Links To Point At Other Pages[edit]

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.

Use Sections Related To Page Type[edit]

We use recurring outlines to organize page content. Some pages summarize and organize the wiki: Regions, high-level Topics, types of workgroups or efforts. These pages use Dynamic Page Lists to curate our collection and present options for exploration. We always leave a section for questions. There is almost no arena of life where thoughtful questions aren't more useful than hasty answers.

Efforts[edit]

Effort pages should describe a complete body of work over time to achieve a particular purpose. What we call "projects" are often too small (and are often an artifice of funding). Don’t piecemeal efforts, and don’t separate feasibility from monitoring. An effort page should tell the whole story, gathering together a suite of projects to tell a coherent story of a body of work at a meaningful scale.

The Blurb - The blurb generally identifies "who did what where and when and for what purpose" in bold text.
Links - if available then provide a few stable links to a website. More links can be provided in the notes: sponsor promotional sites, agency contract database reports, project partner mentions, news articles, etc.
Chronology - The timing of events is useful to know, often forgotten, and is hard to reassemble after the fact.
Notes - Notes are the core section describing the nuances of the effort, lessons learned, and related topics. Avoid long descriptions of methods and instead point to products. Don’t explain topics, but rather point to, and contribute to relevant topic pages. For example, consider contributing to the Topic Page Engineered Log Jams, rather than providing general information on an effort page.
Products - An effort usually results in some products that document the work. This may include a gallery of images.
Related Pages - Consider adding a Content Template.

Workgroups[edit]

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[edit]

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[edit]

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[edit]

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.