Although we are free to make the wiki as beautiful and creative as our imaginations allow, in order to act as an effective knowledge commons for our community, we encourage the use of robust and consistent citation and formatting. There are a number of ways to cite content on the wiki. Let's use this entry as a way to begin the discussion around best practices with the goal of settling on a style guide we can point users to.

Formatting Basics

  • use bold to highlight the entry name the first time it appears in the entry
  • don't use double spaces. Because of how web pages work, one or both of them will get converted into a non-breaking space. As that non-breaking space gets moved around and copied, it messes up layout of pages, particularly on smaller / mobile screens.
  • use Heading 1, Heading 2 or Heading 3, as appropriate, to delineate sections of the entry
  • don't use extra line breaks or other white space for layout. It may look great on your screen, but odds are very good it will wrap strangely on someone else's

Links

There are two basic kinds of links in the wiki, internal and external, which either stay on the wiki website or go to another website. In general, it's best to use internal links in the body of an entry, and put all the external links at the end, or in a section with other info like address, phone number, etc.

 Internal links link to another page on the wiki, and look like normal web links, with blue text and and underline. You create these by selecting text, clicking on the link tool, and entering the name of the page, no http:// or any of that stuff. The default name is the text that you selected, but if you start typing a name, the wiki will automatically give a list of matching pages.

External links link to a page on another website, and look like normal web links, but also have an arrow and box icon before them. This lets the reader know they'll be leaving the wiki and going to another website. They need to start with http:// or https:// to be recognized.

There are a few types of external links that get special icons, including:

Dates

For clarity, please use the format YYYY-MM-DD for dates (ex: for news articles). [source] (Note that this does not mean you should write, “I was born 1985-01-01 at 08:30:45 PST”; but, say for example, in a list of dated items with one per line, putting the date first and expressing it this way means that sorting lines alphabetically also sorts by date … yes, it’s unambiguous for a global web, but it’s also about finding ways to let the machine do the hard work.)

Living Legend vs. Historic Person

One of the most basic distinctions about Oakland people is whether they are still alive ("Living Legend") or dead ("Historic Person"). Except in very unusual circumstances (such as zombism), entries people should be tagged with only one of these tags.

Oakland Wiki Citation Styles

Numbered citations with references at the bottom of the entry

  • Example: Gertrude Stein or Chinatown
  • Benefits:
    • This is most likely the most useful citation mechanism for the reader, especially if the editor adds links to the superscripts.
  • Drawbacks:
    • Time-consuming to update when new references are introduced.
    • References can easily get mis-ordered and confused.
  • Comments:
    • I’d favor this idea if this wiki supported it (wikipedia does). Having to update citations manually is a drag — Mike
    • From my understanding, since there's no "table of contents" function on localwiki, we can't make superscripts link to the correct reference at the bottom of the page, but this would be ideal. - Marina

Unnumbered references at the bottom of entry/no citations in text

  • Example: Veterans' Memorial Building or Tubbs Hotel
  • Benefits:
    • Easy to update when new references are added.
    • Beneficial when a reference provides much of the backbone for the entry's content and cannot be easily tied to a particular location in the text of the entry.
  • Drawbacks:
    • Difficult to know which part of the entry text is tied to which reference.
  • Comments:

Numbered citations with superscript linking to original source

 

  • Example: Malonga Casquelourd Center for the Arts
  • Benefits:
    • This is also one of the most useful citation mechanisms for the reader - the link is right there, no need to even scroll down.
  • Drawbacks:
    • References can get mis-ordered and confused.
    • No provisions for non-internet sources (ie, books or archival materials). For these kinds of citations, can enter either the full reference for the reference in-line (which can make the entry cluttered for the reader) or do a short "author, year" with a full reference at the bottom (clearer for the reader, more work for the editor, possibly a more difficult citation system to learn for a new editor). Alternately, this can encourage the creation of entries for books (an entry for a book can then be the place where the "[source]" link points. Alternately, alternately, we can point "[source]" links to WorldCat or Open Library, although these will not be useful for all books or for archival materials.
    • A link on a single superscripted number makes for a very small clickable target, and the external link graphic plus the underline makes for visual clutter.
  • Comments:

Linked "[source]" in the text itself

  • Example: Rancho San Antonio
  • Benefits:
    • Provides uncluttered citation directly tied to the text.
    • The fact that it's unnumbered makes it easy to update the entry and introduce new sources.
  • Drawbacks:
    • Less useful for references without an external link (ie, books or archival materials). For these kinds of citations, can enter either the full reference for the reference in-line (which can make the entry cluttered for the reader) or do a short "author, year" with a full reference at the bottom (clearer for the reader, more work for the editor, possibly a more difficult citation system to learn for a new editor). Alternately, this can encourage the creation of entries for books (an entry for a book can then be the place where the "[source]" link points. Alternately, alternately, we can point "[source]" links to WorldCat or Open Library, although these will not be useful for all books or for archival materials.
  • Comments:

Templates ( Discuss... )

  • Here is an Example on SeattleWiki of a right aligned Hours/Contact/Info etc box placed immediately underneath the map : http://seattlewiki.net/International_District_Library
  • Benefits:
    • Never seen that before til a moment ago. It instantly pops out to me as a very inviting approach to further edit that SeattleWiki page:
    • The white space on the LEFT is the invitation for free-hand editing, photos, and so on.
    • The map box and same-width information table box being RIGHT aligned has a very formal template-ish feel to it. I would even say professional feel.
  • Drawbacks:
    • Anyone have any thoughts on this for OaklandWiki Templates?
  • Comments?

Plural vs. singular tags

Plural forms of nouns will normally be canonical. A tag should fill in the blank in a sentence such as “This resource is about…” or So, for example, a page might be aboutcaterpillars, not about caterpillar. This also reflects most common user practice; a user is more likely to search for “caterpillars” rather than for “caterpillar.” Of course, for common terms, both singular and plural forms should be included in the database and mapped to the plural.

However, for very specific terms, the singular might be preferred: You might think of a page as being about the black swallowtail butterfly rather than about black swallowtail butterflies, and a user is more likely to search for the singular form of a highly specific term.

1.http://www.learnnc.org/lp/editions/lpguide/1938#4-2-0

More styles here...

Edit tags