Difference between revisions of "CCS Cataloging Manual:Manual of Style"

From CCS Cataloging Manual
Jump to navigation Jump to search
m
 
(6 intermediate revisions by the same user not shown)
Line 1: Line 1:
The '''Manual of Style''' is a style guide for the CCS cataloging manual.  Please follow it except where common sense and the occasional exception will improve an entry.
The '''Manual of Style''' is a style guide for the CCS cataloging manual.  Its guidelines should be followed except where common sense and the occasional exception will improve an entry.


==Naming conventions==
==Naming conventions==
Line 19: Line 19:
Use the gerund (e.g. "editing" rather than "edit") of verbs unless there is a more common form that makes more sense in context.
Use the gerund (e.g. "editing" rather than "edit") of verbs unless there is a more common form that makes more sense in context.


==First sentences==
==Content==
===Content===
===First sentence===
The first sentence should begin with a simple declarative sentence that summarizes the entry's subject matter.
The first sentence should begin with a simple declarative sentence that summarizes the entry's subject matter.


If possible, the page title should appear once in the first sentence.
If possible, the page title should appear once in the first sentence.


===Format===
The first, and only the first, appearance of the page title should be in '''boldface'''.
The first, and only the first, appearance of the page title should be in '''boldface'''.
===Referring to the database===
Use "in the CCS database" instead of "in the local database" or "locally".
===Citing other rules===
If a specific RDA rule applies, the number may be cited, but do not link to it as rule numbers may be changed.
Other guidelines (e.g. OCLC, OLAC, MLA) may be cited and/or linked as applicable.
See [[#References|References]] for formatting.
===Citing CCS decisions===
If a local practice is adopted by a CCS group (e.g. CAMM Technical Group), cite the group and date.  See [[#References|References]] for formatting.
===General guidelines===
Follow these general suggestions from [https://www.usability.gov/how-to-and-tools/methods/writing-for-the-web.html usability.gov]:
* Use plain language when possible.
* Chunk content into sections, to make it more scannable.
* Use short sentences and paragraphs. The ideal standard is no more than 20 words per sentence, five sentences per paragraph.
* Use bullets and numbered lists, and not just for long lists. One sentence and two bullets is often easier to read than three sentences.
* Add keywords in sentences if that will help discovery.  For example, instead of "Macros" consider using "OCLC Connexion Macros for WorldCat".
* Use neutral, direct language. Instead of "Please remember to change", just use "Change".
* Where applicable, use language similar to that of [https://www.oclc.org/bibformats/en.html OCLC Bibliographic Standards and Formats].


==Text formatting==
==Text formatting==
Line 76: Line 99:
Use an en dash (–, entered as –) in the body text of entries as the typographical equivalent of the word ''through'': Many libraries have fiscal years that run July–June.
Use an en dash (–, entered as –) in the body text of entries as the typographical equivalent of the word ''through'': Many libraries have fiscal years that run July–June.


Use a hyphen instead of an en dash in representations of MARC data: <code>504 &nbsp;Includes bibliographical references (p. 103-120).</code>
Use a hyphen instead of an en dash in representations of MARC data: <code>504 &nbsp;Includes bibliographical references (pages 103-120).</code>


====Em dashes====
====Em dashes====
Line 93: Line 116:
===Tables===
===Tables===
When using wiki markup to create a table, include the [[Template:Table|table template]] at the end of the first line to style the table appropriately.  If manual users will need to re-sort the table by any column, use the [[Template:Sortable|sortable template]] instead.
When using wiki markup to create a table, include the [[Template:Table|table template]] at the end of the first line to style the table appropriately.  If manual users will need to re-sort the table by any column, use the [[Template:Sortable|sortable template]] instead.
===References===
If external resources are relevant to an entire page, use the [[Template:External|external template]] to put a short list of links in a box in the upper right corner of the page.
For references to RDA or other rules, either cite the rule number directly in the text (e.g. "following RDA 2.3.1") or use a footnote in the form "RDA 2.3.1".
For references to CCS decisions, use a footnote in the form "CAMM, March 12, 2016".


==Formatting MARC data==
==Formatting MARC data==
===Referring to subfields===
===Referring to subfields===
{{draftbox|text=
For inline references to a particular subfield, use either: subfield a (written out) or &Dagger;a (entered as <code>&amp;Dagger;a</code>).
In a general reference to a particular MARC subfield, use either: subfield a (written out) or &Dagger;a (entered as <code>&amp;Dagger;a</code>).


In examples of OCLC WorldCat data, use &Dagger;a, via <code>&amp;Dagger;a</code> for in-line text or <code>&#123;&#123;[[Template:Subfield|subfield]]{{pipe}}style=oclc{{pipe}}a&#125;&#125;</code> for MARC-format examples.
For examples of OCLC WorldCat data, use &Dagger;a via <code>&amp;Dagger;a</code> for inline text, or <code>&#123;&#123;[[Template:Subfield|subfield]]{{pipe}}style=oclc{{pipe}}a&#125;&#125;</code> for MARC-format examples.


In examples of WorkFlows data, use {{pipe}}a (for in-line text), entered as <code>&#123;&#123;[[Template:Subfield|subfield]]{{pipe}}a&#125;&#125;</code> for MARC-format examples.
For examples of Polaris data, use &Dagger;a via <code>&amp;Dagger;a</code> for inline text, or <code>&#123;&#123;[[Template:Subfield|subfield]]{{pipe}}a&#125;&#125;</code> for MARC-format examples.
}}


===Referring to MARC indicators===
===Referring to MARC indicators===
{{draftbox|text=
For general inline reference to the value of one of a field's MARC indicators, use the format "first indicator [of] ''indicator value''" (e.g. "first indicator 1" or "first indicator of 1").  Use "[space]" to indicate a blank indicator position.
In a general in-line reference to the value of one of a field's MARC indicators, use the format "first indicator [of] ''indicator value''". (E.g. "first indicator 1" or "second indicator of 1").  Use "[space]" to indicate a blank indicator position.


For in-line references that of the contents of a particular tag when a particular indicator has the mentioned value, use the MARC tag, followed by a space and the indicator(s). Use "_" to indicate a blank first indicator value when there is a non-blank second indicator value. Omit the second indicator when it would be blank. (E.g. "245 14", "100 2", and "264 _4")
For inline references to the contents of a particular tag when an indicator has a specific value, use the MARC tag followed by a space and the indicator(s). Use "_" to indicate a blank first indicator value when there is a non-blank second indicator value. Omit the second indicator when it would be blank. (E.g. "245 14", "100 2", "264 _4")


For in-line references that take the form of a full-field example, follow the guidelines on [[#Excerpts|excerpts]] .
For inline references that take the form of a full-field example, follow the guidelines on [[#Excerpts|excerpts]] .
}}


===Excerpts===
===Excerpts===
Surround with &lt;code&gt;...&lt;/code&gt; any excerpts or examples that are inline within a larger paragraph.  Use two spaces between the tag and the content when both indicators should be blank. Use a space for blank indicators and separate the indicators from the tag and the content with a single space when one or both indicators have a non-blank value.  Examples:
Surround with &lt;code&gt;...&lt;/code&gt; any excerpts or examples that are inline within a larger paragraph.  Use two spaces between the tag and the content when both indicators should be blank. Use a "_" for blank indicators and separate the indicators from the tag and the content with a single space when one or both indicators have a non-blank value.  Examples:
* ''Include a note of <code>504  Includes bibliographical references.</code> to indicate the presence of citations in footnotes throughout the work.''
* ''Include a note of <code>504  Includes bibliographical references.</code> to indicate the presence of citations in footnotes throughout the work.''
* ''When a Playaway record includes <code>710 Findaway world.</code>, delete that field.''
* ''When a Playaway record includes <code>710 2_ Findaway world.</code>, delete that field.''


===Entire fields, multiple fields, and entire records===
===Entire fields, multiple fields, and entire records===
Line 135: Line 161:
245 10 Baseball, hot dogs, and apple pie /{{subfield|c}}by John Smith.}}
245 10 Baseball, hot dogs, and apple pie /{{subfield|c}}by John Smith.}}


==Formatting Unicorn data==
==Formatting Polaris data==
===Policy names===
===Policy names===
Format policy names in all uppercase letters, surrounded by &lt;code&gt;...&lt;/code&gt;. Use &lt;tt&gt;...&lt;/tt&gt; instead in table columns that include only the policy name.
Format policy names surrounded by &lt;code&gt;...&lt;/code&gt;. Use &lt;tt&gt;...&lt;/tt&gt; instead in table columns that include only the policy name.


===Policy types===
===Policy types===
Do not capitalize the names of policy types, such as ''item type'', ''item category 1'', etc.
Do not capitalize the names of policy types, such as ''material type'', ''shelf location'', etc.


==Proposed changes and changes in progress==
==Proposed changes and changes in progress==
Line 153: Line 179:
When the actual rules on an entire page have been approved, but the final wording for the manual is still being reviewed, or when an existing rule has been questioned and is being reconsidered but no final action has been taken yet, insert the [[Template:Review|review template]] as the first line of the page. Use the date= parameter to indicate the date the change was tentatively approved.
When the actual rules on an entire page have been approved, but the final wording for the manual is still being reviewed, or when an existing rule has been questioned and is being reconsidered but no final action has been taken yet, insert the [[Template:Review|review template]] as the first line of the page. Use the date= parameter to indicate the date the change was tentatively approved.


When a new or changed actual rule within a larger page has been approved, but the final wording for the manual is still being reviewed, surround the changed text with the [[Template:Reviewbox|reviewbox template]].
When a rule within a larger page has been approved, but the final wording for the manual is still being reviewed, surround the relevant text with the [[Template:Reviewbox|reviewbox template]].


When converting a "draft box" to a "review box", be sure to delete any duplicated original text as well as any text that had been struck through.
When converting a "draft box" to a "review box", be sure to delete any duplicated original text as well as any text that had been struck through.


===Deletions &amp; Obsolete Rules===
===Deletions &amp; Obsolete Rules===
When someone proposes that an entire page be deleted from the manual, insert the [[Template:Delete|delete template]] as the first line of the page.
When an entire page has been declared obsolete but is retained in order to explain the reason why older data in the database looks the way it does, insert the [[Template:Obsolete|obsolete template]] as the first line of the page.
 
When an entire page has been declared obsolete but needs to be retained in order to explain the reason why older data in the database looks the way it does, insert the [[Template:Obsolete|obsolete template]] as the first line of the page.


When a particular rule within a larger page has been declared obsolete but needs to be retained for historical reasons, surround the text with the [[Template:Obsoletebox|obsoletebox template]].
When a section of a page has been declared obsolete but is retained for historical reasons, surround the text with the [[Template:Obsoletebox|obsoletebox template]].


==Redirection==
==Redirection==

Latest revision as of 20:59, 17 September 2018

The Manual of Style is a style guide for the CCS cataloging manual. Its guidelines should be followed except where common sense and the occasional exception will improve an entry.

Naming conventions

Use the most easily recognized name

Whenever possible, an entry should use a name that will be most easily recognized, with a minimum of ambiguity and a maximum of clarity.

Use sentence case

Capitalize the first word in an entry name or section name. Do not capitalize the second and subsequent words unless they should normally be capitalized.

Singular vs. plural

Use singular forms of nouns for entries unless the entry deals with a small class of material or when the noun is always plural.

Use plural forms of nouns for categories, as they represent a group of things.

Avoid initial articles

Do not begin an entry or section name with an initial article.

Use gerund forms of verbs

Use the gerund (e.g. "editing" rather than "edit") of verbs unless there is a more common form that makes more sense in context.

Content

First sentence

The first sentence should begin with a simple declarative sentence that summarizes the entry's subject matter.

If possible, the page title should appear once in the first sentence.

The first, and only the first, appearance of the page title should be in boldface.

Referring to the database

Use "in the CCS database" instead of "in the local database" or "locally".

Citing other rules

If a specific RDA rule applies, the number may be cited, but do not link to it as rule numbers may be changed.

Other guidelines (e.g. OCLC, OLAC, MLA) may be cited and/or linked as applicable.

See References for formatting.

Citing CCS decisions

If a local practice is adopted by a CCS group (e.g. CAMM Technical Group), cite the group and date. See References for formatting.

General guidelines

Follow these general suggestions from usability.gov:

  • Use plain language when possible.
  • Chunk content into sections, to make it more scannable.
  • Use short sentences and paragraphs. The ideal standard is no more than 20 words per sentence, five sentences per paragraph.
  • Use bullets and numbered lists, and not just for long lists. One sentence and two bullets is often easier to read than three sentences.
  • Add keywords in sentences if that will help discovery. For example, instead of "Macros" consider using "OCLC Connexion Macros for WorldCat".
  • Use neutral, direct language. Instead of "Please remember to change", just use "Change".
  • Where applicable, use language similar to that of OCLC Bibliographic Standards and Formats.

Text formatting

Italics

Emphasis
Use italics rather than uppercase letters for emphasis in the body of entries.
Incorrect: Do Not Delete The Title Field.
Incorrect: Do NOT delete the title field.
Correct: Do not delete the title field.
Use italics sparingly to emphasize words. The more words you emphasize, the less effect each emphasis has on the reader.
Words as words
Use italics when referring to a word, letter, or string of words or letters as a word, letter, or string of words or letters.
Examples:
The term cataloging means "to catalog".
The most common letter in English is e.
Foreign terms
Use italics for foreign terms that are not commonly used in everyday English. For example: "Microfilm cataloging is a bête noire for many catalogers."
Do not use italics for loanwords and borrowed phrases that are in common use in English. For example: "Beta tapes cannot be played in VHS machines and vice versa."

Non-breaking spaces

A non-breaking space is recommending to prevent breaking apart elements of an expression that would be awkward on the beginning of a new line, such as 10 cm. This is done by using &nbsp; instead of a space: 10&nbsp;cm yeilds 10 cm.

Because multiple non-breaking spaces are not collapsed down to one space by web browsers, non-breaking spaces can also be used to force a certain number of spaces to display when not using <pre> markup or the example template.

Quotations

Use quotation marks for quotations of a sentence or two.

Use <blockquote>...</blockquote> for quotations of more than four lines or more than one paragraph. Surround each paragraph with <p>...</p>. Include the attribution for the quote in a separate paragraph inside the blockquote, starting with a — (&mdash;) without a trailing space.

Apostrophes and quotation marks

Use standard straight apopstrophes and quotation marks rather than curly quotes.

Acronyms and abbreviations

Except with the most-commonly-used acronyms and abbreviations (e.g. MARC, OCLC), generally use the spelled out form of a term the first time it appears in an entry, followed the acronym or abbreviation in parentheses. If the term is already in parentheses, use a comma and or instead of nesting parentheses.

Use standard English rules for plurals of acronyms and initialisms. In other words, generally use -s or -es and do not use an apostrophe.

Serial comma

Use a serial comma (also known as an Oxford comma or Harvard comma) immediately before the conjunction in a list of three or more items.

Dashes

En dashes

Use an en dash (–, entered as &ndash;) in the body text of entries as the typographical equivalent of the word through: Many libraries have fiscal years that run July–June.

Use a hyphen instead of an en dash in representations of MARC data: 504  Includes bibliographical references (pages 103-120).

Em dashes

Use an em dash (—, entered as &mdash;) in the body text of entries instead of a double hyphen (--).

Use a double hyphen instead of an em dash in representations of MARC data: 500  "Special 50th anniversary edition"--Cover.

Using color

Do not use color alone to convey information, as the information will not be accessible to people with color blindness or on black-and-white printouts. Using color may be desirable in some cases, but the information should still be accessible without it.

If color is required, try to choose colors that are unambiguous (such as orange and violet) when viewed by someone with red-green color blindness and do not use shades of red and green as color codes in the same example.

Invisible comments

Use <!-- and --> to flag an issue or leave a comment or instructions for other editors in the body text of an entry that should not be seen by the average reader.

Tables

When using wiki markup to create a table, include the table template at the end of the first line to style the table appropriately. If manual users will need to re-sort the table by any column, use the sortable template instead.

References

If external resources are relevant to an entire page, use the external template to put a short list of links in a box in the upper right corner of the page.

For references to RDA or other rules, either cite the rule number directly in the text (e.g. "following RDA 2.3.1") or use a footnote in the form "RDA 2.3.1".

For references to CCS decisions, use a footnote in the form "CAMM, March 12, 2016".

Formatting MARC data

Referring to subfields

For inline references to a particular subfield, use either: subfield a (written out) or ‡a (entered as &Dagger;a).

For examples of OCLC WorldCat data, use ‡a via &Dagger;a for inline text, or {{subfield|style=oclc|a}} for MARC-format examples.

For examples of Polaris data, use ‡a via &Dagger;a for inline text, or {{subfield|a}} for MARC-format examples.

Referring to MARC indicators

For general inline reference to the value of one of a field's MARC indicators, use the format "first indicator [of] indicator value" (e.g. "first indicator 1" or "first indicator of 1"). Use "[space]" to indicate a blank indicator position.

For inline references to the contents of a particular tag when an indicator has a specific value, use the MARC tag followed by a space and the indicator(s). Use "_" to indicate a blank first indicator value when there is a non-blank second indicator value. Omit the second indicator when it would be blank. (E.g. "245 14", "100 2", "264 _4")

For inline references that take the form of a full-field example, follow the guidelines on excerpts .

Excerpts

Surround with <code>...</code> any excerpts or examples that are inline within a larger paragraph. Use two spaces between the tag and the content when both indicators should be blank. Use a "_" for blank indicators and separate the indicators from the tag and the content with a single space when one or both indicators have a non-blank value. Examples:

  • Include a note of 504 Includes bibliographical references. to indicate the presence of citations in footnotes throughout the work.
  • When a Playaway record includes 710 2_ Findaway world., delete that field.

Entire fields, multiple fields, and entire records

Use the example template to display longer examples of MARC data in a special box with a fixed-width font. Use the subfield template for all subfield codes inside this sort of example, as well as for examples of MARC-format data that are inline within a larger paragraph.

{{example|text=504 Includes index.}}
displays as:

504  Includes index.

{{example|text=
100 1 Smith, John.
245 10 Baseball, hot dogs, and apple pie /{{subfield|c}}by John Smith.}}

displays as:

100 1  Smith, John.
245 10 Baseball, hot dogs, and apple pie /‡cby John Smith.

Formatting Polaris data

Policy names

Format policy names surrounded by <code>...</code>. Use <tt>...</tt> instead in table columns that include only the policy name.

Policy types

Do not capitalize the names of policy types, such as material type, shelf location, etc.

Proposed changes and changes in progress

Drafts

When an entire page is still just a draft that has not been approved, insert the draft template as the first line of the page.

When an addition to an existing page is still just a draft, surround the addition with the draftbox template.

When an alteration to an existing page is still just a draft, copy the text to be changed, use <s> tags to strike through the old text, and surround the alteration with the draftbox template.

Under Review

When the actual rules on an entire page have been approved, but the final wording for the manual is still being reviewed, or when an existing rule has been questioned and is being reconsidered but no final action has been taken yet, insert the review template as the first line of the page. Use the date= parameter to indicate the date the change was tentatively approved.

When a rule within a larger page has been approved, but the final wording for the manual is still being reviewed, surround the relevant text with the reviewbox template.

When converting a "draft box" to a "review box", be sure to delete any duplicated original text as well as any text that had been struck through.

Deletions & Obsolete Rules

When an entire page has been declared obsolete but is retained in order to explain the reason why older data in the database looks the way it does, insert the obsolete template as the first line of the page.

When a section of a page has been declared obsolete but is retained for historical reasons, surround the text with the obsoletebox template.

Redirection

Create a redirect page to an entry page for the following cases:

  • From an abbreviation
  • From a common misspelling
  • From an alternative spelling
  • From a plural when an entry title is a term that does not follow the standard conventions for plurals
  • From a singular when a category title is a term that does not follow the standard conventions for plurals
  • From a alternative term or phrase
  • From a page title with other capitalizations when the page title contains mixed case other than the very first letter. (All page titles with all initial capitals or all lowercase letters except for the very first letter are found using a case-insensitive match when a searcher clicks the "Go" button, but mixed-case titles must found via "Go" using an exact case match.)

Be careful when creating a redirect category to a category page because the Mediawiki software does not prevent pages from being linked to the redirect category instead of the target category. This should not be a major problem in a minimal-access wiki like this one, but is something to watch out for.