Style Guide for Contributors

Titles & Section Headings

When first creating a page, be sure to put a title at the top. For continuity, the wording should match the wording of any link text on other pages that points to the new page.

The main title should be formatted as the dominant text on the page ("Heading 1" is the largest option). Subordinate headings should be smaller. This page, for example, uses Heading 1 for the main title, "Style Guide for Contributors," and Heading 4 for the section headings.

In titles, capitalize all nouns, pronouns, verbs, and other words four letters or more.

Style & Usage

Write concisely. People don't read Web sites the way they do print material. They scan, looking for bits and pieces of informatin they can pick up quickly. If the article continues beyond a single visible screenful, carve it up into "chunks," if possible. Use section headings, bullets, and bold-face type to assist the scanners.

When using acronyms, spell out the full version of the phrase in first reference, followed by the acronym in parentheses.

Use Red to Invite Contributions

For links to pages that have yet to be created or that need fleshing out, add a red asterisk (*) before and after the link to help draw it to our users' attention. For example: * Name of Article We Need * or * Name of Article That Needs More Detail *

In the WYSIWYG editor, just type the asterisk, select it, and click on the text color icon (the letter "A" sitting atop a red bar); then click on the red square in the color palette.

If you're using markup language (in the raw editor), surround the asterisk with the code for red, as follows:

%RED%*%ENDCOLOR%

Similarly, use red text when writing guidance, suggestions, and requests for contributions so that would-be contributors can easily spot this material. Once the contributions have been made, delete the red guidance text.

Institution-specific Information

Many articles will contain information that is useful to a broad audience as well as information that applies more narrowly to those at an individual institution. For clarity and relevance to the right audience, separate the institution-specific information--either in a section toward the end of the article or in a stand-alone page that is linked to from the broader article.

Links and Organization

When creating, re-purposing, or editing content, take advantage of the Web's cross-referencing powers by adding links where appropriate. Links can be especially useful in providing definitions of terms and pointing to helpful related information--within this wiki as well as outside of it. Similarly, when creating a new page, it is a good idea to establish links to it from other pages so that users are more likely to be aware of the your new page.

Although the TWiki platform on which this wiki is built makes it easy to create new links and refer to existing links through the use of "wiki words" (see this discussion), this may not be the most user-friendly approach. We recommend that link text generally be in the form of titles and phrases that look like standard English: We suggest, for instance, What Do Regulators Classify as Research, rather than WhatIsResearch.

When creating a new page, think about where you are creating it (within the wiki's informational space) and what its its "parent page" should be. For example, if the list of terms you are creating relate only to research ethics, then the page listing those terms probably is best located in the wiki's ethics area, perhaps using the Ethics Overview page as its parent. While most people come to most material on wikis through direct searches (and not by browsing through information hierarchies), it is nonetheless helpful to users to see where pages "fit in."

Discuss These Guidelines