Issue 541: Small Edits Checklist
Post by Philippe Michon on June 6, 2021:
Currently, there is no formal process to identify small errors and/or typos in the CIDOC CRM documentation. If a user notices, for example, a spelling mistake in the text, two options seem possible:
-
Write an email for an editor to correct the mistake;
-
Create a dedicated issue.
Both options seem not quite adequate: on the one hand, sending an email can discourage those who are not familiar with the structure of the SIG and, on the other hand, the issues should be used for substantive discussions rather than for minor edits.
For this reason, should we put in place a tool that would allow anyone to identify minor errors in the CIDOC CRM documentation and which would also be used by editors to follow up? If so, do we think a spreadsheet with a structure similar to this would be a good place to start? Note that this document is currently hosted on the Canadian Heritage Information Network's Google Drive, but if everyone agrees this is relevant, it should be hosted by the SIG.
In the context of this issue, I would particularly like to obtain your comments on the following questions:
-
Should this be implemented?
-
Does this type of tool/document seem relevant to us?
-
Do we like the current structure or would it be better to make some changes?
-
How should we make this document accessible? Is one link in this issue sufficient?
-
Regardless of where the document is published, would it be relevant to present the objectives and a tutorial on how to use this document in a few paragraphs?
-
Any other questions to discuss?
Kind regards,
Philippe
Post by Pat Riva (15 June 2021)
I agree with Philippe that a tracking tool for small edits is a good idea. In my experience translation projects do tend to notice all these small imperfections in the source document. The translator has to figure out what was meant to do the translation. If there is no quick way to document them, it is easy to lose the opportunity to make the corrections.
There are also likely to be similar small editorial points discovered in the extensions, and eventually also in the translations. If the same file is shared, it will need a column to indicate which model and which language. Or there could be distinct files along the same pattern.
Pat
In the 50th joint meeting of the CIDOC CRM SIG and SO/TC46/SC4/WG9; 43nd FRBR – CIDOC CRM Harmonization meeting, the SIG reviewed HW by PM (spreadsheet for listing typos and formatting inconsistencies in CIDOC CRM v7.1.1).
Decision:
- checklists must be implemented periodically and a guideline on how they're to be kept up to date must be incorporated in GBs HW for issue 354.
- this particular checklist to appear on the website
June 2021
Post by George Bruseker (7 October 2021):
Dear all,
In this HW I was charged with:
"checklists must be implemented periodically and a guideline on how they're to be kept up to date must be incorporated in GBs HW for issue 354.
this particular checklist to appear on the website"
It is my proposal that this document appear in the proposed new guidelines and translations resources sections of the overall reconfigured resources section of the SIG website.
( see last sentence of HW 528 proposal)
https://docs.google.com/document/d/1BiGrX_pieVCCwlNf-JQweHkwTp57mfY58SIPxBvwkhw/edit
For your consideration.
Best,
George
Post by Erin Canning (8 May 2022)
Dear all,
The Small Edits Checklist that Philippe created as part of Issue 541 has now been put into use for identifying and correcting typos and other small errors found in the CRM documentation. Now that a workflow has been put into place for making the identified corrections, we would like to make this available to a wider range of people to submit errors that they have noticed: to this end, we have prepared a Google Form that can be used to collect responses, that then logs the submissions in our spreadsheet to be addressed. You can find the Google Form here: https://docs.google.com/forms/d/e/1FAIpQLSem8fVDj1ZCJf-75AaCPcioUBq3O6geVipuaf56CxxqLh_VCA/viewform
We look forward to discussing the potential usefulness of this at the upcoming SIG meeting.
Best,
Erin
In the 53rd CIDOC CRM & 46th FRBRoo SIG meeting, PM showed the small edits checklist. He explained what the fields on the checklist stand for and how they should be filled in. The spreadsheet in its “current” form –when presented at the 53rd Sig meeting –can be found here.
Nb. Since the spreadsheet is difficult to maintain, EC has created a google form, the answers to which will inform the spreadsheet –users will not need to worry about formatting etc.
EC showed the form that informs the small edits checklist. The “Language” column has been removed, in the sense that the google form could be duplicated for crm translations.
Discussion points:
- some of the fields are repetitive (discouraging to use)
- follow-up email confirmation
- extend the checklist beyond CRMbase. Single form for base and family models or different form per model? Maintaining a separate form per extension can be difficult).
- referenced versions: mainly 7.1.2 (the one to be submitted to ISO) and 7.2.1.
- Nb. re. family models: only the maintained versions for family will be listed
Proposal: To slightly edit the google form (cover all extensions), keep number of fields at an absolute minimum, explicitly list CRMbase v7.1.2 and 7.2.1 –and “currently” maintained versions of family models – and set up a follow-up email. Discuss where to place it (so people can use it).
The list should be updated in a monthly basis.
Decision:
- Establish a cut-off point beyond which v7.1.2 will no longer be edited (at which point it will be removed from the checklist)
HW: EC & PM to edit the google form as suggested. - Re. the position of the document on the site (“supplementary material”) –see issue 596. HW for the team at FORTH to propose a structure and implement it. The list should be updated in a monthly basis.
Overall discussion re versioning of the CRMbase:
v7.1.2 should start to be translated into the ISO format. In that sense, there is a small margin to further edit it. The decisions made throughout the 53rd Sig meeting should also be included in the version to be submitted to ISO. Once this has been done, typos found in v7.1.2 should be corrected in v7.2.1.
May 2022
Update of Checklist 16 May 2022
Philippe and Erin have amended the form based on the meeting's feedback and subsequent comments from Athanasios Velios and Wolfgang Schmidle.
New form: https://docs.google.com/forms/d/e/1FAIpQLSdfuoTDMU9MUl3i81DzzgVNIC4WN0bO5l5O58g-cbogOWiohA/viewform
Summary of changes:
|
# |
Critique |
Action |
|
1 |
Make the form shorter |
Changed to short answer and merged a few specific location questions The form has been streamlined to 9 questions |
|
2 |
“Location” questions feel repetitive |
Changed from drop-down to short answer or simpler drop-down |
|
3 |
Unclear if this is for just for classes and properties, or introductory materials too |
Q5's description mentions that the proofreading error can be anywhere in the documents (“class”, “property”, or “other eg. introductory materials” options) |
|
4 |
Send follow-up email to the person with overview of their submission |
Triggered “collect email addresses” option and set to always send submission |
|
5 |
Don’t need all the version options |
Added a drop-down menu for Q4 which contains the latest CIDOC CRM version number. This list will be updated regularly |
|
6 |
Extend for other extensions |
Q4 lists all the extensions and translations options (including the latest version number) |
|
7 |
Change the word “error” to something less intense sounding |
Changed to “proofreading error” |
|
8 |
Link to Issue #541 should not be in the form description |
Removed the link, the link will be added on the CIDOC CRM webpage dedicated to the form |
In the 54th CIDOC CRM & 47th FRBR/LRMoo SIG meeting, the issue was closed on the grounds on therebeing nothing left to do. It was decided (see 596) that the small edits checklist and the form that generates it will appear on the site under the new link: Home\Editorial Suggestions.
Rome September 2022