View source for Help:File naming convention

The naming convention outlined in this document is intended to facilitate the organization and retrieval of documents produced and archived by the Dried Fish Matters project.

All documents stored in the project data management systems should be named according to this guideline. This includes all project-generated files shared through OneDrive, Dataverse, Zotero, and the DFM website.

Although it is preferable that document authors should follow the naming convention at the time of document creation, the project management team may also rename shared documents as necessary to maintain a consistent naming protocol.

=Rationale=

#Deep folder hierarchies are opaque and time-consuming to navigate, and potentially challenging to maintain if the document classification system is complex or needs to change.
#Conversely, information-rich filenames are identifiable in a shallow context (e.g., when shared by email or surfaced in a directory search), as their content can be determined independently of the storage location path.
#Groups of related files can be listed and sorted meaningfully if the name components follow a general-to-specific data pattern. Filenames that include a common prefix and a year-month-day date string (YYYY-MM-DD) display chronologically within a group of related documents, for instance, when viewed in a folder sorted alphanumerically by filename.
#File and folders that are consistently named following a controlled vocabulary can easily be retrieved, sorted, and filtered according to the core criteria reflected in that vocabulary. Relevant criteria for our purposes are document type (work plan, invoice, academic article, interview, etc.) and research team / country.
#It is helpful to distinguish between working copies of documents, draft versions that have been circulated for comments, final published versions, and revised or corrected versions of a previously published document. While word processors can embed tracked changes and comments within a draft document, it is lways useful to maintain copies of “snapshot” versions that have been published or circulated for comments – ideally in a non-editable format such as PDF –  as these revisions can more easily be referenced outside the source document itself.
#Shared folders are most usable if they logically contain files that are related to a specific activity. The files in a given folder should relate to a single task or project, rather than a content criterion (e.g., document type), so as to facilitate the creation of ad hoc work teams and to avoid the need for team members to have access to documents distributed across multiple folders.

=DFM file naming convention=
File names following the DFM file naming convention are made up of three or more informational parts or '''tokens''' joined with an '''underscore''' character (<code>_</code>).

There should NOT be any punctuation characters in the filename; always use '''hyphens''' instead of spaces.

==Minimum requirement==
At minimum, a document requires the project prefix (<code>DFM</code>), a three-letter document code (see below), and a descriptive title. For example, the following is a minimally descriptive filename for fieldnotes conducted at Cox’s Bazar, using the code <code>OBS</code> for “Observational notes”:<blockquote><code>DFM_OBS_Coxs-Bazar.docx</code></blockquote>

==Creating meaningful filenames==
A more meaningful filename includes additional descriptive tokens. For example, the above file could be renamed to include the author (<code>MH</code>) and date (<code>2022-02-20</code>). It could also specify a more precise locator (<code>drying-yards</code>):<blockquote><code>DFM_OBS_MH_Coxs-Bazar-drying-yards_2022-02-20.docx</code></blockquote>

==Abbreviations==
The document title token (<code>Coxs-Bazar-drying-yards</code> in the example above) should have a maximum of approximately 30 characters, as some popular computer operating systems may fail to access files where the full directory path and filename exceed about 250 characters.

Abbreviations can be used in the document title if their meaning is clearly documented or otherwise apparent. For instance, the abbreviation <code>CB-DRY</code> could be meaningful in the example given here, if an accompanying reference document indicates that files tagged <code>CB</code> relate to Cox’s Bazar, and that files tagged <code>DRY</code> relate to fish-drying sites or activities:<blockquote><code>DFM_OBS_MH_CB-DRY_2022-02-20.docx</code></blockquote>

==Document revisions==
When updating an office document (such as Word, Excel, or PowerPoint), avoid renaming the source document. Retaining a single source document on OneDrive, instead of making copies, will preserve edit history in one place.

Documents for circulation or archival should be exported to a PDF with a name that includes date, status (<code>DRAFT</code>, <code>FINAL</code>, or <code>PUB</code>), and revision tokens as applicable (e.g., <code>rev01</code>). We can take, for example, this source document:

<blockquote><code>DFM_GDL_Sample-project-guideline.docx</code></blockquote>

Successive versions of this same document could be exported to PDF for circulation as follows:<blockquote><code>DFM_GDL_Sample-project-guideline_2020-09-04_DRAFT.pdf</code>

<code>DFM_GDL_Sample-project-guideline_2020-10-06_DRAFT_rev01.pdf</code>

<code>DFM_GDL_Sample-project-guideline_2020-10-10_FINAL.pdf</code></blockquote>

=File naming tokens=
The following table summarizes the tokens that should be in use.
{| class="wikitable"
!'''Token'''
!'''Description'''
|-
|'''General prefix'''

(required)
| Always |<code>DFM</code> for documents generated by the Dried Fish Matters project. 

Guidelines, templates, and regulations pertaining to partner or funder organizations can be prefixed otherwise where applicable (e.g., <code>UM</code>, <code>SSHRC</code>).
|-
|'''Document type''' 

(required)
|A code that indicates the document type (see codes below). 3 characters, upper-case.
|-
|'''Organization/author code'''

(optional)
| a token indicating the researcher, institution, or research team to which document pertains. This can be three-letter country code (see below), last name initials of an individual researcher (e.g., |<code>Johnson</code> or <code>DJ</code>), or the acronym of an institution (e.g., <code>VSS</code>, <code>CEPA</code>). 

The organization code is mandatory for contracts and reports.

Research documents produced within a team can be described using acronyms that identify both the team and individual contributors within it (e.g., <code>KHM-GL</code> for “Cambodia – Gayathri Lokuge”)
|-
|'''Title'''

(required)
|A filename that briefly describes the document contents. Maximum 30 characters.
|-
|'''Date''' 

(required for exported PDF; sometimes optional with source document)
|The document release date, in YYYY-MM-DD format. 

The date token should always be included in the filename of a PDF exported for distribution or archival.

The editable source document must also have a date string if it provides a record of activities or events on a specific date (e.g., meeting minutes, observational fieldnotes, interview). The “Modified” timestamp or document metadata cannot always be used reliably to determine the date when a document was written.

The date token is optional for a document that is not date-specific, provided there is only one working version of the document.
|-
|'''Status'''

(required for exported PDF; optional for source document)
| the status of document, if it has been released for distribution – typically |<code>DRAFT</code> if the document is being circulated for comments and revisions, <code>FINAL</code> for a signed contract or similar internal document to which further updates are not expected, or <code>PUB</code> for a document circulated to the general public. If a status tag is used, a date should also be given.

The status token should always be included in the filename of a PDF exported for distribution or archival. It may optionally be used with the source document filename.
|-
|'''Revision'''

(optional)
| the revision number, as a two-digit zero-padded preceded by string “ |<code>rev</code>”. Begin with <code>rev01</code> (NOT <code><s>rev1</s></code>) to facilitate alphanumeric sorting (“rev11” will sort before “rev2” but after “rev02”).

The revision token should always be used in combination with a status token.

The revision token should be included in the filename of a PDF exported for distribution or archival.
|}

=Examples=
This document is named <code>DFM_GDL_File-naming-convention.docx</code>. The filename consists of the following elements:

*<code>DFM</code>: General prefix
*<code>GDL</code>: Document type token, signifying “Guideline”
*<code>File-naming-convention</code>: Document title token

A second example might be a file named <code>DFM_PLN_IND_Y1-work_2018-08-07_DRAFT_rev02.pdf</code>. This is a DFM planning document related to India, setting out work in Year 1. The document draft was circulated for a third round of comments (after a second revision) on August 7, 2018. The <code>DRAFT</code> notation could be changed to <code>FINAL</code> or <code>PUB</code> if the document is subsequently approved for final distribution and will no longer be revised. This filename consists of the following elements:

*<code>DFM</code>: General prefix
*<code>PLN</code>: Document type token, signifying “Plan”
*<code>IND</code>: Organization code token, signifying “India”
*<code>Y1-work</code>: Document title token
*<code>2018-08-07</code>: Document release date token
*<code>DRAFT</code>: Document status token
*<code>rev02</code>: Document revision token, signifying this is the second revision of the draft

=Token codes for document types=
These codes may be updated from time to time as project needs evolve.

Use the generic token <code>DOC</code> (“Document”) if nothing else fits.

{| class="wikitable"
! colspan="2" |Research protocols and instruments
|-
|<code>PTC</code>||Research protocol or instrument (questionnaire, consent form, list of procedures)
|-
! colspan="2" |Research data
|-
|<code>DAT</code>||Structured dataset (database, csv file, spreadsheet, QDA file)
|-
|<code>FIG</code>|| Figure (graphic, chart, diagram). Sketches made in the field should be classified as |Figure (graphic, chart, diagram). 
Sketches made in the field should be classified as <code>OBS</code> for “Observational notes”.
|-
|<code>IMG</code>||Image (photograph). See separate guidance on naming and cataloguing photographs.
|-
|<code>INT</code>|| interview or survey responses (response sheet, audio-visual recording, notes, transcript). Structured data combined in spreadsheet database form should be tagged |Interview or survey responses (response sheet, audio-visual recording, notes, transcript).
Structured interview or survey data combined in spreadsheet or database form should be tagged <code>DAT</code> for “data”.
|-
|<code>MAP</code>|| Map or plan drawing. Sketch maps produced in the field should be classified as |Map or plan drawing. 
Sketch maps produced in the field should be classified as <code>OBS</code> for “Observational notes”.
|-
|<code>MEM</code>||Research memo or note (analytic memo, commentary, annotation)
|-
|<code>OBS</code>||Observational fieldnotes or recording (participant observation notes, video clip, observational sketch)
|-
! colspan="2" |Research outputs
|-
|<code>PUB</code>|| Publication: text intended for general, public circulation (article, book, chapter, policy brief, report). Conference presentations should be tagged |Publication: text intended for general, public circulation (article, book, chapter, policy brief, report)
Conference presentations should be tagged <code>PRS</code> for “presentation” if they are primarily oral communications.
|-
|<code>RPT</code>|| Internal report (financial report, activity report). A research for general circulation should be tagged |Internal report (financial report, activity report)
A research report for general circulation should be tagged <code>PUB</code> for “publication”.
|-
! colspan="2" |Meetings, conferences, and workshops
|-
|<code>AGN</code>||Meeting agenda
|-
|<code>MIN</code>||Minutes and notes
|-
|<code>PRS</code>||Presentation (slides, notes, audio or video recording, paper text, transcript) from a meeting or conference.
|-
! colspan="2" |Working documents and operational guidelines
|-
|<code>COR</code>||Correspondence to and from external parties (letters, emails, newsletters). Correspondence will typically be archived within separate systems, specifically the project mailing list archive and internal mailboxes. Signed correspondence sent as email attachments, or exported copies of email messages, may be retained outside those systems for easier reference.
|-
|<code>PER</code>||Personnel info (contact details, banking information for wire transfers, CV, etc.)
|-
|<code>PLN</code>|| Planning document (timeline, plan, etc.). Tag as |Planning document (timeline, plan, etc.)
Tag as <code>TOR</code> if the plan is formalized within a contract or other agreement.
|-
|<code>TOR</code>||Terms of Reference. This token applies to formal contracts and agreements including Transfer of Funds Agreements, Independent Contractor Agreements, and Research Sub-Agreements. The TOR will typically define payment terms, an outline of work to be undertaken, and reporting obligations.
|-
! colspan="2" |General / internal communications (supplied by DFM Winnipeg)
|-
|<code>GDL</code>||Guideline (checklist, recommended procedures, protocol, etc.)
|-
|<code>HLP</code>||Help document (manual, tutorial, instructions). Provides information on how to access and use a database or computer software, how to submit a required report, etc.
|-
|<code>TPL</code>|| Document template (Word document, blank form, poster template). This category is intended for project communications. Forms and templates to be used in research data collection should tagged |Document template (Word document, blank form, poster template)
This category is intended for project communications. Forms and templates to be used in research data collection should be tagged <code>PTC</code> for “protocol”.
|-
! colspan="2" |Project management, reporting, and administration
|-
|<code>BDG</code>||Budget (spreadsheet, planning, or tracking document)
|-
|<code>CLM</code>||Claim for expense reimbursement
|-
|<code>INV</code>||Invoice
|-
|<code>RCT</code>||Receipt
|-
|<code>TSH</code>||Timesheet
|-
! colspan="2" |Token codes for researchers and teams
|-
|<code>BGL</code>||Bangladesh
|-
|<code>CAN</code>||Canada
|-
|<code>IND</code>||India
|-
|<code>KHM</code>||Cambodia
|-
|<code>LKA</code>||Sri-Lanka
|-
|<code>MMR</code>||Myanmar
|-
|<code>THA</code>||Thailand
|}