IWG Wiki style guide

From MediaWiki

The Imaging Wiki Style Guide extends the existing AIC Wiki Guidelines and takes inspiration from the Wikipedia Manual of Style and the Wikipedia Layout. It outlines the conventions for writing, formatting, and presenting content on the Imaging Wiki. Adhering to these guidelines ensures a consistent and easily digestible experience for all users. This guide complements the IWG Wiki Content Policy.

General principles[edit | edit source]

Tone and voice[edit | edit source]

Contents should maintain a professional and objective language in a fluent tone. Content should be informative, suitable for a professional knowledge base. Avoid colloquialisms, slang, and overly casual language. The goal is to inform, not to lecture, entertain or persuade.

The third person must be used throughout. Avoid "I," "we," "you," or direct address to the reader.

Use a Neutral Point of View (NPOV) as outlined in the Content Policy. Present information fairly, without bias, and avoid advocacy for specific products or methods unless it represents widely accepted best practices.

Conciseness and clarity[edit | edit source]

Be direct and to the point. Every sentence should contribute to the understanding of the topic. Avoid unnecessary words and redundant or verbose phrases.

One idea per paragraph. Each paragraph should typically focus on a single, coherent idea or sub-topic (large blocks of text are intimidating and difficult to read on a screen). If you find a paragraph addressing multiple distinct points, it's a good candidate for splitting.

Use headings generously. If a section becomes too long (e.g., more than 5-7 paragraphs), consider if it can be broken down further with more specific sub-headings.

Keep related information together. Ensure that logically connected information remains within the same section or closely linked subsections.

Divide and conquer. Create a new Wiki page for information or topics that are true across multiple pages (e.g. equipment, physical principles, workflows). Consider creating new Wiki pages also to address concepts and information that are too complex to be presented in one section or that detour from the page’s subject.

Technical language[edit | edit source]

Assume a target audience of conservation professionals, students, scientists, photographers and imaging specialists. While clarity is paramount, a certain level of foundational knowledge can be assumed.

Minimize the use of jargon. Adequately explain its meaning when it is used, and link to (and if necessary populate) the Glossary of terms.

Consistency[edit | edit source]

Be consistent throughout the Wiki page.

Use the Style Guide as guidelines, rather than strict rules.

Verifiability and copyright[edit | edit source]

The content should be verifiable by referencing credible, published sources.

Quotations should be integrated smoothly into the text rather than interrupting the flow with large blocks of unintegrated text. Paraphrasing the content of a published source ensures flexibility of editing and integration to the page and keeps copyright infringements at bay.

Stick to the IWG Wiki Content Policy for copyright and licensing guidance.

Wikilinks, references, and external links[edit | edit source]

Wikilinks link different pages and sections across the whole AIC Wiki, offering an interconnected web of knowledge to the user who can explore concepts and information by jumping from topic to topic.

  • Only create Wikilinks when they are genuinely relevant to the current discussion and helpful for the reader's understanding or further exploration. Does linking this term provide valuable additional context, definition, or related information that enhances the user's understanding of the current page?
  • Don't overdo: introduce Wikilinks at first occurrence in the section.
  • Link only to pages, not to a section of a page (#anchor).
  • Creating a Wikilink to a non existing page will redirect to a new page that can be created and edited.


References should only be compiled via the built-in tools (in-text citation and reference list).

Links to resources outside of the AIC Wiki must be confined to the Further reading section of the page and formatted as a bibliographic reference following the latest edition of the Chicago Manual of Style (note, annotated bibliography).

URL addresses should never be expressed in full: the link should always be incorporated in the text without referring to "click here" or similar expressions.

Conventions[edit | edit source]

Language and syntax[edit | edit source]

American English is the language of choice throughout the Imaging Wiki.

Proper names in other languages should be written following the original spelling (e.g. “Opificio delle Pietre Dure”, “Centre de recherche et de restauration des musées de France”).

The use of universally accepted terms, rather than those less widely distributed, especially in titles, is preferable.

Avoid contractions (e.g. “does not” instead of “doesn’t”).

Avoid phrases such as “remember that” and “note that”.

Avoid embellishments and don't be pushy: don’t tell readers that something is interesting, ironic, surprising, unexpected, amusing, coincidental, etc.

Capitalization[edit | edit source]

Titles and section headings should use Sentence case, not Title Case.

Titles of books, articles, media works and artworks follow title case formatting (e.g. “A Clockwork Orange”).

Retain the original style for titles of works in other languages.

Capitalize names of specific institutions, but not generic words for institutions (e.g. "a museum of modern art" and "the Museum of Modern Art").

Capitalize “The” at the start of an institution's name only if it’s part of the official name (e.g. “The Metropolitan Museum of Art”, “The British Museum”, but “the Uffizi Galleries”).

Abbreviations and acronyms[edit | edit source]

Introduce the full expression at first occurrence followed by the abbreviation or acronym in parentheses (e.g. “The Metropolitan Museum of Arts (The MET)”).

Do not use apostrophes to form plurals.

Avoid abbreviations when they might confuse the reader, interrupt the flow, or appear informal.

Italics[edit | edit source]

Italics are used for emphasis, titles of original works, and non-English words (except proper names).

Date and time[edit | edit source]

Full dates are formatted “June 10, 1921”.

Months are capitalized (e.g. “February”).

Do not use “the year” before the digits (“1995”, instead of “the year 1995”).

Decades are written in the format the 1980s.

Years are denoted by CE and BCE instead of AD and BC (if relevant).

Terms such as "current", "now", and "recent" should be avoided. What is current today may not be tomorrow.

Numbers[edit | edit source]

Integers from zero to nine are spelled out in words.

Other numbers may be expressed either in numerals, words, or in forms like “3 million”.

Use a point for decimals.

Use commas to group digits to the left of decimals. Numbers with four digits are at the editor’s discretion (“3000” or “3,000”).

Write “3%” or “three percent”, but not “3 %” (with a space) or “three %”.

Intervals of dates and numbers should be separated by a double dash between two spaces (“ – “).

Units of measurement[edit | edit source]

The use of the metric system is preferable.

When the use of a different system is unavoidable, provide the conversion in parentheses (e.g. “22 pounds (10 kg)”).

Where space is limited (such as tables, parenthetical notes, and mathematical formulas) unit symbols are preferred.

Use "per" when writing out a unit, use a slash with symbols (e.g. “lumens per steradian” and “lm/sr”, but not “lumens/steradian”).

Layout[edit | edit source]

Page titles[edit | edit source]

The names of wiki pages should be succinct and descriptive of the topic.

Avoid duplicating page titles; pages with similar titles should have some indication of why they are different.

Minimum viable layout[edit | edit source]

The simplest page should contain at least:

  • An introductory paragraph (or lead section),
  • One citation,
  • A reference section.

Lead section[edit | edit source]

An article's content should always begin with an introductory lead section (a concise summary of the article).

It is never divided into sections.

It defines the topic, summarizes its main points, and provides context for the conservation imaging field. It should ideally be understandable on its own and contain key information first.

Example of prompt questions:

  • What is the primary subject of this article?
  • How would you define this subject in a single, clear sentence for a conservation professional?
  • What is its fundamental purpose or function in conservation imaging?
  • What are the main techniques, methods, or approaches associated with this topic?
  • What are its primary applications or benefits within cultural heritage conservation?
  • What are the core principles or scientific foundations that underpin this topic?
  • Are there any critical limitations, challenges, or safety considerations?


An introductory image is desired for the lead section.

Infoboxes, images and other related content in the lead section must be right-aligned.

Article body[edit | edit source]

Pages are generally divided into sections, and sections over a certain length are generally divided into paragraphs.

PARAGRAPHS[edit | edit source]

Aim for 3-7 sentences per paragraph (50-150 words).

Each paragraph should focus on a single, coherent idea or sub-topic. If a paragraph addresses multiple distinct points, it's a good candidate for splitting.

Short paragraphs are (kind of) OK. A single sentence can deliver a powerful message, but what is implied for you may not be the same for the reader.

Ideally, the first sentence of each paragraph should introduce its topic.

SECTIONS AND SUBSECTIONS[edit | edit source]

Aim for 3-5 well-structured paragraphs (and appropriate sub-sections). Try to keep sections of manageable length.

If a section becomes too long (more than 5-7 paragraphs), consider if it can be broken down further with more specific sub-headings.

One sentence doesn’t make a section. Sub-sections should be meaningful enough to warrant their own entry in the table of contents (ToC).

Try to avoid level 3 and level 4 subsections to ensure adequate readability throughout the page.

Bibliography[edit | edit source]

The Further readings section should include only resources that were not cited in the text but that can turn useful to the reader.

The References section is automatically compiled when in-text citations are added.

Templates[edit | edit source]

Templates can generally be used across the page, preferably above the next section heading.

Templates with general callouts should be placed before the lead section.

Formatting[edit | edit source]

Templates[edit | edit source]

Use templates to standardize and manage repetitive content, such as notices, warnings, and info boxes.

New templates can be created directly from the URL bar (keep the IWG prefix):

https://www.conservation-wiki.com/wiki/Template:IWG[NewTemplateName]

Templates can be formatted with HTML and CSS attributes. For a matter of consistency, it is preferable that templates for the Imaging Wiki follow the formatting below:

<span>
     <div style="
     padding-top: 15px;
     padding-left: 15px;
     padding-right: 15px;
     background-color:Color1;
     border-width: medium;
     border-style: solid;
     border-color: Color2;
     ">
     
     '''Lorem ipsum dolor sit amet.'''<br>
Lorem ipsum dolor sit amet [[Wikilink|Displaytext]].

</div>
</span>

Titles and headings[edit | edit source]

Use headings in order: do not use Heading 2 (Sub-heading 1) if there is no Heading 1 (Heading) preceding it.

Titles and section headings should use Sentence case (“Infrared radiation imaging” instead of “Infrared Radiation Imaging”).

Do not use articles ("A", "An", or "The") as the first word unless it is an inseparable part of a name or of the title of a work.

The final character should not be a punctuation mark unless it is an inseparable part of a name or an abbreviation, or when a closing round bracket or quotation mark is required.

Use Heading 1 and 2 only. If Heading 3 cannot be avoided, it should be formatted with BOLD UPPER CASE to ensure readability.

Section headings should:

  • Be unique within a page (so that section links lead to the correct place);
  • Not contain links (especially where only part of a heading is linked);
  • Not contain images, icons, emojis;
  • Not contain <math> markup;
  • Not contain citations or footnotes;
  • Not misuse description list markup (";") to create pseudo-headings;
  • Not contain template transclusions;
  • Not refer to a higher-level heading, unless doing so is shorter or clearer;
  • Not be numbered or lettered as an outline;
  • Not be phrased as a question;
  • Not use color or unusual fonts.

Quotations[edit | edit source]

Use double quotation marks (“ ”) instead of italics for quotations (the Block quote formatting does not work).

Consider paraphrasing long quotations to avoid the risk of copyright infringement.

Quotations must be attributed and the source explicit with the built-in citation tool, and the wording of the quoted text must be faithfully reproduced.

If the quotation is in a language other than English, provide a faithful translation between ("parentheses and quotation marks") for in-text quotations and in italics for block quote.

Tables[edit | edit source]

Use distinct and concise labels for all column headings.

If applicable, include units of measurement directly in the column heading (e.g., “Wavelength (nm)”). If units vary, specify the unit in the cell after the digits.

Group related data logically into rows and columns.

Each column should contain a consistent type of data (e.g., all numbers, all dates, all text descriptions).

Always add a descriptive but brief caption to summarize the content and purpose.

Avoid merged cells unless it’s unavoidable.

Tables with wikitable style are preferable.

Sortable and collapsible tables are welcome.

The table caption goes here.
Column 1 Column 2 Column 3
Category 1 Numbers Numbers
Category 2 Numbers Numbers
Category 3 Numbers Numbers

Bullet and numbered lists[edit | edit source]

Only use the built-in numbered and bulleted list function.

Use indentations for child items.

Use numbers rather than bullets only if the sequence of the items is critical (e.g., a workflow).

End each list item with a comma ( , ) or a semicolon ( ; ). The last list item must end with a period ( . ).

Each list item is formatted with Sentence case.

Add a blank line break after the list if it is followed by a paragraph.

Citations and references[edit | edit source]

In-text citations should be reported only as superscript format using the built-in citation tool. Do mention the (Author date) in the text.

Citations should be added after punctuation marks.

Use the latest edition of the Chicago Manual of Style (note, annotated bibliography).

Use a reference manager (such as www.mybib.com) to automate the citation formatting. Creating a project for each page helps keeping track of the literature.

When a citation has a DOI or a URL address, incorporate it in the title of the work and do not express the address in full:

Adams, Savannah. 2022. “Lights, Camera, & More Lights: The Role of Lighting in Conservation Photo Documentation.” Bunsen and Bronte: C-U at the Lab. University of Illinois Library. August 18, 2022.

Insert the automatic Reference list after the Reference heading at the bottom of the page. Do not manually add references to this section.

Further readings[edit | edit source]

This should go at the bottom of the page, just before the Reference section.

Report the reference with the usual formatting and link in the work’s title:

Museum Learning Hub. “Module 3, Technical Workshop 3: Imaging Standards and Logistics in Digitization Projects.” YouTube, July 5, 2021.

Possibly, add a brief annotation about the resource and apply the Preformatted style:

Museum Learning Hub. “Module 3, Technical Workshop 3: Imaging Standards and Logistics in Digitization Projects.” YouTube, July 5, 2021.

Elizabeth Chang provides a detailed overview of the equipment and space setups, technical imaging standards and how these standards contribute to long term digital preservation plans, as well as tools for ensuring that the digital files have the longest lifespan.

Media[edit | edit source]

Dos and don’ts[edit | edit source]

Alt text should be added to all uploaded media.

Attribution should be mentioned in the media comment and in the caption.

Media should be added right below the section heading to which they relate:

== Heading 2 ==
[[File:PhotoSetupRTI.jpg|right|thumb|Caption. Attribution, CC BY 3.0|alt=Alt text.]]

All media should be right-aligned.

All media should be boxed and have a caption.

Preferably, embed media with thumb dimension.

/---/

Media should not be positioned above the next heading.

Text should not be sandwiched between media.

Avoid numbering illustrations (e.g. “Figure 1”).

Avoid referring to images as being to the left, the right, above or below. Contents move around on different devices and displays.

Images[edit | edit source]

Name the files with a succinct and descriptive title before uploading: “ImagingLab000511 (1).jpg” is not a good file name.

Recommended size is 1024 x 768 pixels at 2MB or less. Online compression tools (such as https://freetinypng.com/) can be used to optimize images for web usage.

Embedded YouTube videos[edit | edit source]

The AIC Wiki does not have a built-in tool to embed content.

YouTube videos can be embedded using HTML and CSS attributes to format them in a right-aligned box with a custom caption:

<div class="thumb tright">
 <div class="thumbinner" style="width: 430px;">
 {{#widget: YouTube|id=VIDEO ID}}<br/>
<div class="thumbcaption">CAPTION.
</div>
</div>
</div>

YouTube playlists can be embedded as well:

<div class="thumb tright">
   <div class="thumbinner" style="width: 430px;">
   {{#widget: YouTube|playlist=PLAYLIST ID}}<br/>
<div class="thumbcaption">CAPTION.
 </div>
</div>
</div>

A 430px frame contains well the video for desktop (not tested on mobile or tablet yet).

Captions[edit | edit source]

Always include a caption to identify the illustration.

Always include the source and the attribution license. Use the Creative Commons tool to choose a suitable license for your media.

Captions should be succinct; more information can be included on its description page, or in the main text.

Captions for technical charts and diagrams may need to be substantially longer than usual; they should fully describe all elements of the image and indicate its significance.

Avoid numbering illustrations (e.g. “Figure 1”).

Avoid referring to images as being to the left, the right, above or below.

Categories and category pages[edit | edit source]

Category[edit | edit source]

Whenever possible, assign a category to a page. This is done from the page settings pop-up window accessible from the the editing menu bar.

Maintain a logical organization of categories.

Category pages[edit | edit source]

Category pages list, in alphabetical order, all the pages under that category.

Providing a general overview of the pages and an alternative semantic organization is good practice, but optional.

The table of contents is optional for category pages. It can be disabled from the page settings pop-up window accessible from the the editing menu bar.

Sub-category[edit | edit source]

To create a sub-category, assign the parent category to a category page.