LPedia:Manual of Style

From LPedia
Jump to: navigation, search

This is presently an incomplete proposal mainly based on actual practice.

Articles vs. Documents

LPedia is not Wikipedia. Unlike Wikipedia, which is based on the model of an encyclopedia, LPedia is more like a library. LPedia includes encyclopedia-style articles, including articles based on or describing historical documents, but it also includes the historical documents themselves.

The terms "article" and "document" are used in various ways in different contexts. Encyclopedias are organized into articles, but so are newspapers and magazines. The Mediawiki software and associated documentation often use the term "article" to refer to a wiki's primary structural unit -- a block of formatted text with a permanent identity, which can link to other such articles and in turn be linked to by other such articles. These units might sometimes also be called "pages", as they appear in a web browser in the same way as pages presented by other software. (However Mediawiki actually uses the same sort of structure to store text that describes the wiki itself, including help files and templates used in constructing other articles -- all of these are "articles" in that sense.)

In addition, like other wiki software, Mediawiki also allows for storage and retrieval of "files" which could also be representations of text but in a more traditional format, e.g., a PDF, plain ASCII, a format associated with some particular word-processing software, or even a scanned image of a page of text. In other words, the distinction between "article" and "file" in the context of discussing the software and related tools is one of storage format (which of course in turn has implications for how they are created and updated.)

This, however, is not the distinction with which we are primarily concerned with respect to LPedia policy. In the context of policy, the important distinction is between encyclopedia-style articles and "documents". By "document" we mean something of historical value that consists of text (or primarily of text) which had its own existence prior to and independent of LPedia. These properties do not require that such text be represented using any particular technology -- indeed the "same" document might be represented in more than one way. In particular, there are many cases where it is useful to represent such documents using exactly the same technology as for the encyclopedia-style articles, i.e., as pages formatted using the wiki formatting language. But even though they may be stored the same way, they serve a different purpose in the overall structure of LPedia, so they need to be discussed separately with respect to formatting guidelines and other policies.

encyclopedia article historical document
role in LPedia to explain some aspect of the LP
to summarize material from documents or other articles
to serve as a catalog/index/guide to other encyclopedia articles
to serve as catalog/index/guide to documents
to preserve/display something that existed independent of LPedia
representation wiki text (in the default namespace) wiki text (in a designated namespace)

or

PDF, TXT, TIFF, etc. (in the file space)

examples an article about the history of the Platform
a list of national conventions
an article about a particular convention
an article describing LP News
a chart showing the history of LP News formats, editors, circulation
the text of the Platform for a particular year
the minutes of a convention
an issue of LP News
an individual article from LP News
a press release
source created within LPedia, by LPedia writers/editors created outside LPedia, by organization officer, committee chair, newsletter editor, etc.
(imported into LPedia some time after original publication/distribution)
update policy continuously edited to correct, amplify, and keep up-to-date, in accordance with customary wiki management practice static -- generally not subject to update except for formatting changes applying to an entire class of documents and not subject to correction except for errors in the original transcription/import process


Conventions Relating to (Encyclopedia-Style) Articles

Note: These conventions do not apply to "Documents", even if represented as wiki-text..

General Conventions

This subsection discusses some conventions that apply generally to encyclopedia-style articles. For additional conventions that apply to specific types of articles, see the Standard Structure for Articles on Various Subjects section below.

Article and Link Titles

  • All titles should be in title case, not sentence case: New York Election Results, not New York election results.
  • Titles should use the minimum amount of punctuation necessary, and should avoid use of characters that have special meaning in wikitext.
  • No title in the default name space should begin with a word followed by a colon, as this could be (or could come to be) in conflict with a namespace identifier.

Info Boxes

Standardized info boxes that provide basic information about a subject can help readers quickly get the information they need without hunting through the entire article. There are templates available for creating info boxes for various types of articles. If articles on a particular type of subject normally have an info box, then one should normally be included in any new article on that type of subject. For guidance relating to some common article types, see the "Standard Structure for Articles on Various Subjects" section below.

Section Headings

  • All headings should be in title case, not sentence case: External Links, not External links.

Personal Names

Titles and headings that include the name of a person should use the form that that the person most commonly uses/used, and if there is more than one common form the simpler of them. For additional information, see the "Articles about People" section below.

Dates

Dates in article titles and headings should be written in the general form Day Month Year, or as much of that as makes sense to identify the article or section. The month name should be fully spelled out (i.e., "April" rather than "Apr" or "Apr.", and the year should be the full four digits (i.e., "1988" rather than "88"). For articles and sections about subjects that relate to a whole year rather than a specific date, or about events that take place only once per year (e.g., a convention), normally only the year would be included in the title or heading. Similarly for articles or sections that relate to a month or about events that take place monthly.

Standard Structure for Articles on Various Subjects

Articles about State and Local Parties

(to be added)

Articles about Meetings

Following are standard structures for articles about conventions and LNC meetings. A similar structure might apply for meetings of other types. Section headings would only be included if there is actually corresponding content.

Conventions
  • articles about conventions should in most cases have a title that starts with "National" or the name of a state, then the word "Convention", and then the year; additional words describing the type of convention ("Nominating", "Platform") may be added in the case of special conventions or if the affiliate normally divides convention work up that way, but words like "Annual" or "Regular" which don't distinguish different types should not be included
  • intro paragraphs (before first heading) - first paragraph basic info about convention (date, location, who was presiding, any special circumstances), additional paragraphs mentioning highlights / important decisions
  • certain basic information should also be presented in an info box using the Convention template
  • heading "(Agenda and) Minutes" - link(s) to document(s) containing the formal (agenda and) minutes
  • heading "Other Reports of this Convention" - links to other documents that describe what happened at this convention (e.g., a newsletter article, a press release)
  • heading "Reports Presented at this Convention" - list of reports from officers, staff, platform committee, bylaws committee, etc. presented to the delegates during this meeting or in preparation for this meeting
  • heading "Elections" - tabulations of the results of elections conducted during the convention (e.g., party officers, nominations for public office)
  • heading "Recordings" - links to audio or video recordings of this convention
LNC Meetings
  • intro paragraphs (before first heading) - first paragraph basic info about meeting (date, location, who was presiding, any special circumstances), additional paragraphs mentioning highlights / important decisions
  • heading "(Agenda and) Minutes" - link(s) to document(s) containing the formal (agenda and) minutes
  • heading "Other Reports of this Meeting" - links to other documents that describe what happened at this meeting (e.g., a report written by a Regional Representative to the state chairs in his/her region, an LP News article, a press release)
  • heading "Reports Presented at this Meeting" - list of reports from officers, staff, committees, etc. submitted to the LNC during this meeting or in preparation for this meeting
  • heading "Recordings" - links to audio or video recordings of this meeting

Articles about People

  • The title of an article about a person should have as its title the form of that person's name that that the person most commonly uses/used, and if there is more than one common form the simpler of them. In most cases this will be a personal name and last name. The personal name will in most cases be the person's actual first name, except when the person consistently used something else, such as a nickname. Middle names should not normally be included, i.e., Walter Block instead of Walter Edward Block, except in situations where there would be a name collision this way (Gary Johnson and Gary Johnson) or if the person is/was normally referred to using a middle name. Redirects with middle names and initials should be created. Initials have been presented without periods at the end -- Percy L Greaves, not Percy L. Greaves. (Among the reasons for simplified names is to reduce the chances of stray red links when the person has an article, and to reduce bot confusion when mining the wiki for data.)
  • Basic facts about the person should be included in an info box using the Infobox Person template.
  • The fully presented name with all names and titles, unabbreviated if the full names are known, should be in bold in the opening sentence or at least paragraph. e.g., Walter Edward Block, PhD or Percy L Greaves, Jr. Similarly, if the person was known by some other name or alias that wouldn't be obvious, that should also be mentioned in the first paragraph.
  • Depending on the roles that the person played in the LP, additional sections should follow with information about party positions, campaigns, or other activities.


Conventions Relating to Historical Documents

Documents may be represented as wiki-text or as traditional "files". Either way, since the purpose of including documents in the wiki is to allow users access to the original document content, preserving the original content is the primary consideration in matters of conversion, formatting, and so on. The details of exactly what will be preserved will necessarily depend on the presentation format. There is a trade-off among presentation consistency, ease of use, and fidelity to the original. However, in general all conversions/presentations should, at the very least, preserve the basic text itself, including spelling, capitalization, and punctuation as in the original.

Conventions for Representing Documents as "Files"

Documents already available in commonly-used formats such as PDF can be conveniently uploaded without conversion. Documents that were originally made available in a format that is no longer in common use, or which depend on proprietary software (e.g., Microsoft Word) should generally be converted to a more common form (e.g., PDF). Documents that were originally made available only in hardcopy form may be scanned and either uploaded in the form of an image (e.g., as a TIFF) or after conversion to some sort of text file. If there is any question about whether any transformation adequately preserves the original content, the best practice is to make multiple versions available.

In any case, any or all such versions that are uploaded as "files" will be given names in the file space. See the File Names section below for naming conventions. Information about the original source and conversions should be recorded in the file description section of the upload page.

Conventions for Representing Documents as Wiki Text

Documents may be represented in the form of wiki text, i.e., using the same mechanism as for an encyclopedia-type article, but different conventions apply.

Page Names

Pages representing documents should be given names in a namespace designated for this use. This serves multiple purposes: it signals to the user that this content is a static document, it allows for separate management of naming conventions and avoidance of certain potential sources of name conflicts, it allows for selective searching, and it may be used in the future for selective management of updates.

Currently there is one namespace designated for this purpose, the "Document" namespace. In other words, documents are stored with names like "Document:LNC Policy Manual 3 July 2007", while encyclopedia-style articles are stored with names from the default namespace, with no prefix, like "LNC Policy Manual". Pages in the Document namespace are automatically displayed with a distinctive background color; there is no need to include separate formatting information to mark them in this way, nor should there be any attempt to override this for a particular page.

The main part of the name (after "Document:") should be chosen to clearly identify the type of document and to distinguish it from other documents of the same type. In most cases, this will mean a name consisting of a phrase identifying the document type followed by some form of date. This is analogous to the convention for naming files, but with full words rather than abbreviations and components separated by spaces rather than underscores or hyphens.

Note that the page names should be chosen for clarity and should as much as possible be consistent among pages representing a series or other collection of documents of a particular type. The page name need not be (and typically will not be) identical to the top line of the title page of the original document. For example, if in creating reports of conventions the secretary for one year put "1992 Convention Report" at the top and the secretary for the next year put "Report of the 1993 Convention" at the top, the corresponding Document pages should still be named in a uniform way: "Document:Convention Report 1992", "Document:Convention Report 1993", and so on. The original title and any other identifying text that appeared at the beginning of the original document should be preserved as part of the page content.

Since many different Libertarian Party organizations may have documents of the same type (e.g., bylaws), consideration should be given to this in choosing names for document pages. In general, if there is any reason to believe that the same terminology for a type of document is in use both by the national LP and by state affiliates, this distinction should be included in the associated page names. Pages for national documents should include the word "National" (e.g., "Document:National Bylaws 2012") unless there is already something in the name that clearly implies national (e.g., "Document:LNC Minutes 1 September 1991").

Conversion of Textual Content

The overall purpose of presenting a pre-existing document as wiki text is to make the original text available in a convenient form, while preserving the essential nature of that text. However, since the text was originally not presented in this format, there is necessarily always some sort of "conversion" process involved in doing this. This may include scanning from a paper document, character set conversion, and reformatting, and each of these processes may involve making choices about what aspects of the original need to be preserved and how best to do so.

Such conversions can be complicated by factors such as: (1) the availability of multiple "originals", either in the same or different formats, (2) errors made in the course of earlier conversions, and even (3) errors in the "originals". For a detailed discussion of these considerations see LPedia:Text Conversion Guidelines.

Conversion of Text Highlight/Emphasis

The wiki formatting language provides options for presenting text using italics, bold, underlining, and so forth. To the extent possible, the wiki-text representation of a document should make use of these options to preserve any such features of the original text. Conversely, such options should not be used to mark text that was not so marked in the original.

Section Headings

If the original document is structured using headings in a way that has an obvious correspondence to the sort of structure that can be represented by wiki headings, such headings may be used in the conversion even though the exact style used to display headings (e.g., bold, larger size, different font) will not be preserved. For example, if the original document had a single level of headings, marking off a simple sequence of sections, a simple single-level sequence of wiki headings may be used. If the original document had a hierarchical structure of named sections, subsections, and so on, a corresponding multi-level wiki heading structure may be used. However the textual content of the heading (words, capitalization, punctuation) should be preserved to the extent possible. The guidelines for headings in encyclopedia-style articles, with respect to capitalization and such, do not apply here. If the headings in the original included any sort of section numbering, that should be preserved in the wiki text presentation. Conversely, if the original section headings did not include numbering, neither should the headings in the wiki presentation. Similarly, if the original document did not have section headings at all, headings should not be added to the converted presentation.

Since documents are rarely (if ever) edited, editing links accompanying any section headings are superfluous and potentially misleading -- these should be suppressed using the __NOEDITSECTION__ magic word.

Table of Contents

If the original document included a table of contents, that table of contents should be preserved, including a reasonable approximation of its format, to the extent possible. If the original table of contents included numbering, so should the converted presentation, and if not, then not. Internal links may be added from the text of this table of contents to the corresponding sections of the body, and the automatic generation of an additional table of contents should be suppressed using the __NOTOC__ magic word.

If the original document did not include a table of contents, but the document is large enough that a table of contents would be useful in the wiki presentation, one can be added but it should be done in a way that makes clear that this table of contents was not part of the original document. In particular, for a document that has been converted using standard wiki heading structure, a table of contents may be created automatically as with any other wiki article. A special formatting class is available for this situation that will cause it to be presented in an appropriate way, and may be invoked by the following code:

<div class="doctocnonum">__TOC__</div>

Supplementary Information

Any other text that must be displayed as part of the page in order to be useful to the reader, but which was not part of the original document, must be visually distinguished (e.g., in a box with a different background color, same as for a generated table of contents).

Other information that may be useful to maintainers of the page but which the typical reader doesn't need to see to understand the document (e.g., notes about the original source, or about scanning or other conversion processes that were involved in creating the wiki-text version) can be placed in the corresponding Talk page.

Also notation can be made that the document is available in other formats, typically PDF as in this example, as follows:

{{Docalt PDF|INSERT FILE NAME}}

Which will show up as follows:

Other-Format-Example.png

References to Documents in Encyclopedia-Style Articles

Encyclopedia-style articles will frequently make reference to historical documents, either in ordinary paragraphs or in lists or tables. The appropriate style for such references (displaying the actual name, using less formal link text, use of abbreviations in the link text, etc.) will generally depend on the context of the reference (e.g., whether it is in a table, whether some part of the name is superfluous because it is already obvious from the context), but will in most cases not depend on whether the document is stored as wiki-text or as a "file". References to documents stored as wiki-text will normally be made using a link of the form:

[[Document:name of the particular document|link text]]

while references to documents stored as files will normally be made using a link of the form:

[[Media:filename.ext|link text]]

For example, here are two lines from the LNC Policy Manual article, one pointing to a version of the manual stored as a PDF and one to a version represented using wiki-text:

* [[Media:LNCPM_2001-10-14.pdf|Policy Manual as of 14 October 2001]]
* [[Document:LNC Policy Manual 3 July 2000|Policy Manual as of 3 July 2000]]

Note that because explicit link text is provided, these two links will display the same way, even though the documents themselves are stored differently:

  • Policy Manual as of 14 October 2001
  • Policy Manual as of 3 July 2000

This is as it should be -- in most cases all the user wants to be able to do is display the document, any given document will be stored one way or the other, and there is no need for the user to know how it is stored in order to display it -- he/she just needs to click on the link.

However in cases where the same document is available in multiple representations, it may be appropriate in some cases to provide links to more than one, and in such cases the distinction should be noted somehow, either in the link text or beside it.


File Names

Files uploaded into the file space will normally have names consisting of a main part and an extension, with the extension indicating the format. The discussion that follows is mostly about the main part -- the extension will be determined by the format.

Photographs

Photographs typically relate to one or more of: people, locations, organizations, activities, and dates. In addition, elements of a set of related photographs are commonly identified using sequence numbers, assigned either automatically by the camera or after the fact by an editor. In general, both to help other users understand to what a photo relates and to minimize name collisions, file names should include multiple components reflecting different aspects of the subject matter, e.g., person and activity, or person and location.

  1. In most cases including at least three components will be helpful.
  2. Single-component file names will almost never be appropriate.
  3. It will almost always be appropriate to include something about the date -- at least the year.
  4. Multiple photos from the same event may include some sort of sequence number if there is no other obvious way to distinguish among them.

Examples of appropriate file names:

  • Ohio-convention-1988-keynote.jpg
  • JohnSmith-mayor-1998.jpg
  • LNC-meeting-2010-03-12-DSC03267.jpg
  • fairbooth-Springfield-MA-1982.jpg
  • 2003-Connecticut-convention-2.jpg

Examples of file names that are NOT appropriate:

  • 12.jpg
  • 20161203.jpg
  • DSC02245.jpg
  • John-Smith.jpg (when? where? doing what?)
  • fairbooth.jpg (when? where?)
  • convention-2012.jpg (where?)
  • California-convention.jpg (when?)

Other Image Files

Other image files containing graphics such as logos and maps should similarly be distinguished from each other through the use of multi-component names. Again, including at least a partial date will usually be helpful.

Audio Files

Audio files should be distinguished by subject, topic, and date. Examples of appropriate file names are:

  • 1996_Nolan_Birth-of-Party.mp3
  • 2002_Smith_War-on-Drugs.mp3


If the files are uploaded to recordings.lpedia.org then _ underscores should be replaced by / slashes and represent subdirectories:

  • 1996/Nolan/Birth-of-Party.mp3
  • 2002/Smith/War-on-Drugs.mp3


Examples of file names that are NOT appropriate:

  • 0894612.mp3
  • nolan.mp3
  • convention.mp3 (when? what party? who?)

Other Files

Files containing formal documents, scanned newsletters, and so on should have multi-component names reflecting the nature of the particular material, with a standard naming convention chosen to allow coverage of both existing and future material of the same type.

Suggested general format:

AFFCODE_SERIESABBREV_YEAR-MONTH-DAY_VOLUME-NUMBER-PAGE_TITLE_AUTHOR

AFFCODE SERIESABBREV YEAR-MONTH-DAY VOLUME-NUMBER-PAGE TITLE AUTHOR
Short code for state or local party

e.g. MA for Massachusetts

(omitted for national documents)

A standardized abbreviation for the general series type (e.g., Platform) or a specific publication (e.g., LPNews) XXXX-XX-XX

e.g. 10/18/67 is

1967-10-18

VX-NX-PX

Such as volume one, number (issue) two, page three is

V1-N2-P3

Title/name of a particular article, section, report, etc., with words separated using hyphens

See-Jane-Run

Last name or committee abbreviation only such as

Doe or PlatComm

(unless more required for disambiguation)

AFFCODE is a short code for the state or local affiliate which published the document or to which the document pertains. For state affiliates, use the common two-letter codes. For local affiliates, use the two-letter code for the state and some short sequence of letters or digits that makes sense based on that state affiliate's organizational structure, separated by a hyphen. For California, use CA-nn where nn is the county/region number.

SERIESABBREV is a standard abbreviation for the series (e.g., publication). Examples of ones assigned so far are (a complete list can found at LPedia:SERIESABBREV):

  • generic (may be combined with affiliate code or not)
    • Bylaws (bylaws, or bylaws combined with standing rules, convention rules, etc.)
    • Platform
    • Program
    • PRrelease (press release)
  • national-specific
    • LPNews (LP News)
    • LPledge (Liberty Pledge or Libertarian Pledge)
    • LNCMIN (minutes of LNC meetings)
    • LNCECMIN (minutes of LNC Executive Committee)
    • LNCPM (LNC Policy Manual)
    • LPEmail (National Party Email)

Note: To avoid potential confusion with affiliate codes, series abbreviations should all be at least three letters long.

YEAR-MONTH-DAY is the publication or listed date which should be in that format (using hyphens); note that for some types of documents only the year may be needed.

VOLUME-NUMBER-PAGE is the volume, number (issue), and page numbers which should be in that format (using hyphens).

TITLE is a shortened form of the title used in the original document, e.g., "Case for a Libertarian Political Party" might become CASE-FOR-LIB-PARTY, "Chairman's Report" might become "chair-report".

AUTHOR is the last name of the author or source committee (for signed articles, reports, etc. only). A list of some standard committee abbreviations can be found here.

Not all documents will have all of these fields. Here are some examples of how this would work.

a TIFF showing page 2 of the October 1982 (volume one, number or issue two) issue of Libertarian Pledge LPledge_1982-10_V1-N2-P2.tiff
a PDF of that entire issue LPledge_1982-10_V1-N2.pdf
a press release issued 15 December 1995 about Bosnia, as plain text PRelease_1995-12-15_Bosnia.txt
National Bylaws from 1996 Bylaws_1996.pdf
Oregon Platform from 1986 OR_Platform_1986.pdf
LP of Santa Clara County Bylaws from 1998 CA-43_Bylaws_1998.pdf

Note that the main components are separated by underscores, with hyphens used between sub-components (e.g. for dates or article titles).

Case should not be considered significant, since files generated by different software may follow different conventions about that.

Needed Conventions

Locations for Tag Templates and Navboxes

Which tags should go where by default?

Presentation of Lists of Historical Activists

A standardized presentation of names, positions, and years could make it practical to mine the state, county, and similar pages for peopel and information to generate article stubs.