Recommended Naming and Distribution of Final and Evolving Documents

For final versions of documents, we are using the following notation for document file names:

Example: 2020013.NSF-CORBI.MapReduce_Geospatial_Algorithm.proposal-body.as-submitted-to-NSF.doc — this is the source file last edited on 1/31/2020.

For a final PDF, there is only one timestamp in the PDF filename, and the timestamp corresponds to the last human edit, not to the date of PDF conversion: 2020013.NSF-CORBI.MapReduce_Geospatial_Algorithm.proposal-body.as-submitted-to-NSF.pdf

For evolving drafts of documents, we are using the following notation for document file names:

Example: 20200131.2300AC_20200130.1500NR.draft.NSF-CORBI.MapReduce_Geospatial_Algorithm.proposal-body.doc — this draft version was released on 1/31/2020 (20200131) at 11pm (2300) by Alex Cahn (AC). Alex was making corrections on the earlier version timestamped at 3pm on 1/30/2020 (20200130.1500) by Nick Richards (NR).

All draft revisions should have at the last and the pre-last timestamps — so that we can verify that no interim version got lost.

Example: the next version may be: 20200131.2330NR_20200131.2300AC.draft.NSF-CORBI.MapReduce_Geospatial_Algorithm.proposal-body.doc

File name syntax:

	20200131.2300	timestamp of last update as YYYY MM DD hhmm (24-hours) (may also be shown as: 2020-01-31.2300)
	AC	initials of the last person who edited
	20200130.1500	timestamp of the previous version that the current version succeeds
	NR	initials of the previous person editing
	draft	mark “draft” for working documents
	NSF-CORBI.MapReduce_Geospatial_Algorithm.proposal-body	full description/title of the document
	.doc	file type

DATE:

All documents, whether drafts or final, have the last edit timestamp or date at the beginning of the filename. Example: 20200821 or 2020-08-21 for 8/21/2020.

DESCRIPTION:

The “description” part of the file name should be a complete title of the document, including the project it pertains to and its critical keywords. Please do not abbreviate any words in the file name (to facilitate a keyword search later). Please do not save on words and give the file a complete and meaningful name — so that it will be easy to find the document later on.

ADVANCED:

DRAFTS:	Include the word “draft” in the names of files that may need further work before external release.


TIME ZONE:	The time is in the Eastern time zone by default (EST or EDT per the season). Our collaborators in other time zones are kindly requested to stamp documents with Eastern time OR to append their time zone abbreviation to the timestamp:
	2020014.0430GMT-NR_20200131.2300AC.draft.NSF-CORBI.proposal-body.doc
	2020013.2030PDT-NR_20200131.2300AC.draft.NSF-CORBI.proposal-body.doc
	(examples of time zones: GMT (=UTC=Z) EST EDT CST CDT MST MDT PST PDT IST CEST CEDT (Central European Summer) IST IDT)

HISTORY:	In intense exchanges of a document, it is often helpful to preserve the date history for more than two steps:
	20200308.0900TG_20200308.0825KS_20200308.0500DLD_2020030808.0038TG_20200307.2100NR_FY2020_draft.MRI_Application_Guidelines.docx.
	The above timestamp prefixes can be truncated to just the times as follows when the date part of the timestamp repeats:
	20200308.0900TG_0825KS_0500DLD_0038TG_20200307.2100NR.draft.FY2020_MRI_Application_Guidelines.docx
LOCKS:	When several people are collaboratively editing a document, we enforce concurrency control to prevent two people from working at the same time on a version. When someone is taking the file to make edits they explicitly “claim the lock” in a message to the group. The lock is automatically granted to the first claimant unless the group's moderator announces a different schedule. The lock is released by sending to the group a new version of the file or by explicitly abandoning the lock.
FINAL VERSIONS:	When a file version is created that is an official version distributable to external parties, that version will have all Word changes "accepted" and the filename will have only one timestamp and no infix DRAFT (unless this is an official document called "DRAFT").
	Example: 20200130.NSF-CORBI.proposal-body.doc

MS-WORD:

TRACKING:	Within the document, we set Tracking on and make sure that MS Word knows the author's name -- so that when the mouse is placed over an inserted text, the insertion's author's name appears. From time to time, the document's moderator might accept all changes to remove clutter. A "clean view" while Tracking is on (as opposed to a "clean version") can be seen at any time in MS Word by selecting a pulldown "No markup" under "All Markup" to the right of "Track changes" in the Review tab.

DOCX MS WORD STYLE:	The document should use a design style template that has an automated numbering of sections, e.g. before starting the document click in the top taskbar: DESIGN > "Black & White (Numbered)". All base text of the document should be in the paragraph style "Normal" under the template. All subheadings should be created using the appropriate paragraph style within the template, e.g., "Heading 2" for a second-level numbered heading. This will make it easy to vertically change the style of the entire document when needed, generate a table of contents, and have a homogeneous text. When deriving a new document from an old un-styled document, please move it into a numbered style template before adding new content. (Unfortunately, this retrofitting may be laborious, but it will save a lot of effort later.)
DOCX FOOTER:	The footer should contain page numbers. In advanced documents, it is often desirable that the footer line of a collaborative draft Word document contain the following auto-updating fields:
	Draft saved by <name of the person who saved the last file><date and time of last file saved><tab><page number>
	An optional template file containing the above footer is at
	CAKE.fiu.edu/20161220__footer_template_for_collaborative_drafts.docx
	The above file also sets an appropriate style template, page numbering, edit tracking, and showing the history of timestamps.

SENDING:

SOURCE DOCUMENT:	Sometimes, final or interim documents are delivered in PDF rather than in a source format because of convenience or the size of the document or because of specialized software needed to open the source format. If so, then we also deliver to Supervisors and Archivists the source versions of the final document and of major interim draft versions.

SENDING DOCUMENTS:	Very large files (over 20MB) are not sent via email. We do not distribute files via a commercial dropbox but via our private uploader/dropbox. For internal delivery of large documents (over 20MB), please use one of OUR cloud services, such as the private Unix dropbox that has been designated for the specific project or user or the organization-wide default private dropbox: n00.cs.fiu.edu/cgi-bin/uploadGen.cgi -- files will be at n00.cs.fiu.edu/Uploaded/DGen -- reading the file back will require a user:password that has been or will be provided. Optionally, if such large files are located on an internal Unix system and are intended for internal consumption only, then instead of uploading, it is also OK to send them via a Unix file reference: the full machine-independent filename beginning with "/homes/" and making sure that the recipients have a "read" permission to the file and "execute" permissions to the entire directory hierarchy containing the file.

Our public dropbox uploader for delivery to external parties is: n00.cs.fiu.edu/cgi-bin/uploadShare.cgi -- after uploading a file, the system will return to the user a publically shareable URL of the file. Please always communicate the full URL of the uploaded file, beginning with "http:".

EXTERNAL:

EXTERNALLY PRODUCED DOCUMENTS:	When we archive a document received that is not named per our nomenclature, we rename it with a full timestamp, author, and full title. If the timestamp is not obvious from the document and it is believed to have been authored or revised last shortly before it was sent, we use the timestamp of the email received. If we know only the month, e.g. 8/2020, then the timestamp is 202008. If we know the month approximately, e.g. within a couple of months of 8/2020, then the timestamp form is "202008c" (c=circa). Likewise for only the year known or the approximate year known the timestamps are "2020"and "2020c".

REVISING EXTERNALLY PRODUCED VERSION:	the external version is first renamed as above, and then new timestamps and initials are prepended.

SEMI-OFFICIAL EXTERNAL DRAFTS:	At times, we are sending a semi-official document labeled DRAFT to an external official. To do that, we take our latest internal document, accept all changes therein, rename by removing all timestamps except the freshest, all initials, and all other internal information, and pre-pending the word DRAFT. Also make sure that the word DRAFT appears inside the document so that it is not forgotten when the document is printed.

OFFICIAL EXTERNAL DELIVERIES:	Typically, official versions of all documents are sent to external parties as clean and compact PDFs, not as source files. When producing a clean PDF from a PowerPoint, please make sure that printing hidden slides is unchecked and name the file beginning with the date, then externally-meaningful description, then the suffix ".ppt.pdf". When producing PDFs from a .docx file, proper options should be set not to print markup or comments. There are, of course, cases when source files need to be officially sent; in these cases, please be careful what internal possibly hidden info may need to be cleansed out from the file content and file name. In all cases, there is only one timestamp in the PDF filename (see above), and the timestamp corresponds to the last human edit, not to the date of PDF conversion.

MULTI-SIGNATORY-SIGNING:

Procedure for asynchronous signing of a document with many signatories.

Phase I:	After a candidate final draft is circulated, each signatory would either reply "OK" to signify their consent to the latest draft OR would state objections OR would claim the lock for editing the draft further (and with the release of their lock, would send a tracked-changes draft named with the new timestamp, initials of the editing person, the previous timestamp, and the word "draft" -- this would help ensure that the process does not accidentally fork).
Phase II:	After all the signatories have given "OK" to the same latest version of the draft, the asynchronous signing commences. Any signatory can "claim signing lock." The first person to claim the signing lock would accept all changes and produce a source file (.doc or .docx) named with the same timestamp as the last draft and the word "draft" replaced with "final." The same person would also convert the source file to PDF, retaining the same timestamp in the name. The version of the file signed by the signatory would have "signed-<initials>" in the filename. Additional signatories, with the release of their signature lock, would add their initials to the filename without changing the timestamp in the filename.

BIBLIOGRAPHY:

There is a special format for posting official versions of published papers:

<paper-handle>.<short paper title>.<short journal or conference name>.<optional indicators>.pdf

Paper-handle:	<author-handle>-<year>-<initials of the first two words of the title>

Author-handle:
-- Single author last name:	Smith
-- Two authors last names:	Smith+Chen
-- Multiple authors, e.g., for "Smith et al.":	Smith-ea (in bibliographic reference: [Smith&al-2023])

Short paper title:	a few first words from the title.

Periods separate clauses within the file name. Within each clause, place “_”, rather than blanks, between words.

Examples:

Paper bibliographic reference:	PDF file name:
[Rishe&al-00-SA] N. Rishe, J. Yuan, R. Athauda, X. Lu, X. Ma, A. Vaschillo, A. Shaposhnikov, D. Vasilevsky, S. Chen. "SemanticAccess: Semantic Interface for Querying Databases." VLDB-2000: Proceedings of the 26th International Conference on Very Large Databases, Cairo, Egypt, 2000.	Rishe+al-00-SA.SemanticAccess.VLDB-2000.vldb.org--downloaded.pdf
[Rishe&al-03-SQ] N. Rishe, J. Yuan, R. Athauda. "Non-Semantic Interface for Querying Databases." PARBASE-2003: Proceedings of the 26th International Conference Small, Databases, Alexandria, Egypt, 2003.	Rishe+al-03-SQ.Non-Semantic_Interface.Parbase2003.Rishe.pdf
[Rishe&al-23-SR] Naphtali Rishe, M. Hadi Amini, Malek Adjouadi. "Scenic routing navigation using property valuation." Journal of Big Data 10, 57 (2023). Springer. 16pp.	Rishe+al-23-SR.Scenic_Routing_Navigation_Using_Property_Valuation.published-downloaded.pdf

This procedure is posted as: Recommended Naming of Documents: cake.fiu.edu/versions-revisions-filenames.txt and cake.fiu.edu/versions-revisions-filenames.html