This page is a style guide for WE1S developers editing the WE1S Bibliography.
(last rev. 25 July 2019)
The WE1S Bibliography Platform
The underlying WE1S bibliography is kept in the WE1S Zotero library. Zotero is a free, open-source bibliography tool and database developed for the scholarly community that can be used both locally (as an app for Windows, Mac, and Linux) and online. It allows a user or group to create, import, tag, and export citations in thousands of citation styles (based on the XML CSL “Citation Style Language”)as exchanged in and out of different bibliography programs through the RIS file format. These styles are available for different disciplines, professional societies, publishers, journals, etc. The WE1S Zotero library publicly available for viewing purposes, but can only be edited by WE1S developers (who need to be included as members of the shared Zotero library).
The WE1S web site (https://we1s.ucsb.edu), which is a WordPress site, uses the powerful Zotpress plugin by Katie Seaborn to pull in citations automatically from Zotero and place them in pages or posts. Configured to connect between the WE1S web site and the WE1S Zotero library, Zotpress allows for looking up citations directly in the WordPress editing interface (through a Zotpress “metabox” in the right sidebar) and use a “shortcode” to place them in the page or post. Shortcodes are brief text strings such as
zotpress tags="Topic model algorithm" style="chicago-fullnote-bibliography" sortby="date" that parameterize a query to the Zotero database. Zotpress shortcodes can be used to automatically download into a page or post anything from an individual citation to all citations sorted or filtered by author, title, date, tag, or item numbers.
WE1S Bibliography Workflow
Commonly, researchers in the WE1S project use a Google form to request that works be added to the project bibliography. The form requests information such as the work’s title, DOI, ISBN, URL, or other partial or full citation information. Partial citation information is often enough for the WE1S bibliography editors (currently Nazanin Keynejad, with Alan Liu) to use Zotero to automatically find and import full citations. (Zotero’s handy ZoteroBib in-browser tool for instant citations can also generate full citations using partial information.) Where possible, WE1S bibliography editors use the best source to generate a citation, privileging official sources and/or sources providing the most bibliographical detail and URLs. The bibliography editors also manually adjust citations as needed to fit WE1S’s Zotero house style.
WE1S Zotero Bibliography House Style
When completing a citation in the WE1S Zotero library, the WE1S bibliography editors check to see that the following fields are populated and compliant with house style:
- Abstract. Where possible, WE1S fills in the “abstract” field in Zotero. Where no official abstract is available, WE1S uses a 5-10 sentence summary of the first paragraph(s) of a work or other useful excerpt as the abstract. For identification purpose, include information about the excerpt in brackets. For example: [First paragraph] indicates the use of the first paragraph in the the source text in lieu of an official abstract. In general, WE1S will summarize all abstracts to fit within a standardized 5-10 sentence entry roll.
- Date. The date field must be filled in with a year (e.g., “2001”). Where a citation has automatically been imported with additional month or day information (e.g., “2001-01-24” or “January 24, 2001”), the date must be simplified into the plain year date. This is because the Zotpress plugin can only sort and title dates by year when it is desired to display citations chronologically on the WE1S web site. (The more exact month/day information is always available to users from the original work.)
- Language. WE1S fills in the “language” field using the top-level ISO 639-1 codes for languages. For example, English is “en”. (WE1S does not use nation-flavored sub-codes as suggested by Zotero, such as “en-US” or “en-GB”.)
- URL. Where possible, WE1S includes the URL or DOI of the work (e.g., its citation page in an online archive such as ACM Digital Library that includes links to the work, or its direct citation in journals or such archives as JSTOR. WE1S does not ordinarily include links to unofficial online copies of works (such as copies on a personal web site or course site).
- Downloads. WE1S does not ordinarily download into Zotero and make available to users the original works even if they are open-access. WE1S relies on providing citations and links.
WE1S Web Site Bibliography House Style
WE1S uses the Chicago Manual of Style citation style. In full bibliographies, WE1S uses what the Zotpress plugin refers to in its shortcode as
style="chicago-fullnote-bibliography". Where desired, WE1S also includes the Zotpress shortcode for the following:
abstract="yes"— Include the abstract of the work.
cite="yes"— include a link labeled “cite” for downloading a citation in RIS format for direct import into a user’s personal Zotero library or other RIS-compliant bibliography tool.
title="yes"— when sorting by date, include the year as a title above each chronological section of the bibliography
showtags="yes"— show under a citation the tags with which it is associated in the Zotero library.
Tags in the WE1S Zotero Library and WE1S Web Site
One of the most powerful features of Zotero and other bibliography systems is the ability to “tag” works with descriptors such as “Topic modeling” or “Social science.” Tagging is especially important in the WE1S bibliography platform because Zotero tags can be used to filter what the Zotpress plugin automatically pulls into the WE1S web site. For example, this Zotpress shortcode pulls in all items in the project’s Zotero library tagged “Topic model interpretation”:
zotpress tags="Topic Model Interpretation" .
For this system of Zotero tags Zotpress web page to work properly, the following considerations should be kept in mind by WE1S developers:
In the Zotero library:
- There must be no punctuation in any tags. For example, use “Topic Model Interpretation”, but not “Topic Model, Interpretation” or “Topic Model (Interpretation)”. Punctuation breaks the automatic mechanism for using Zotpress to pull tagged Zotero items into web pages.
- For consistency, WE1S uses Title Case for capitalizations (capitalizing all words with the exception of prepositions and articles), for example: “Topic Model Interpretation,” not “Topic model interpretation”).
- Often, the automatic import of citations into Zotero by way of a DOI, ISBN, URL, etc., will also import tags included by the publisher or author. These tags should be deleted in the record unless they are part of the WE1S bibliography’s tag taxonomy. WE1S tags should be added. A complete list of approved WE1S tags will be made available to developers. If the need arises to edit the list, the developers will share their recommendations with WE1S and make changes to the taxonomy as needed.
- Tags can be added or revised as needed for the WE1S bibliography, but they should serve a particular purpose (such as supporting desired tag bibliographies or a bibliography included in a page or post). It is not useful to clog the bibliography with miscellaneous tags specific to a work or field that are not used for any real purpose in WE1S. For example, an article on topic modeling Jane Austen novels would be tagged “Topic Modeling” and “Topic Model Applied” for WE1S, but it would not be tagged “Jane Austen.” See above notation on approved WE1S tag taxonomy.
- The WE1S bibliography editors need to be told about any new tags for which a bibliography sub-page (a tag-filtered page) is desired on the web site, since such a page needs to be created. Also, they need to be told about any renaming of an existing tag in Zotero, since the corresponding bibliography sub-pages need to be revised.
In bibliography pages on the WE1S web site:
- Web pages for cumulative views of the bibliography are by author, title, and date. (These pages are already created for the WE1S site.)
- Web pages for specific tags in the bibliography follow a common template (see the source code of any existing tag page).
- When creating a new tag page, WE1S bibliography editors must use the “Page Attributes” metabox in the right sidebar of the editing interface to make the page a child of the “parent” page “WE1S Bibliography”. Otherwise, the URL of the page will not conform to that of other bibliography tag pages.
- The table of contents for the WE1S bibliography (appearing in a grey box at the top of each bibliography page) is created by using the Content Blocks plugin on the WE1S WordPress site. This plugin allows a standard “block” or piece of source code (in this case, that for the bibliography table of contents) to be inserted in the form of a shortcode on any WordPress page or post. When a new bibliography tag page is created, WE1S bibliography editors add a new link in the block for the table of contents. Updating that block automatically updates its appearance everywhere on the WE1S site.