Enhancing concept models with internal notes (maintainer comments)

[skalee]

We need to enhance concept model with some kind of internal notes (maintainer comments). These internal notes are meant to be edited and read by glossary maintainers. They are not going to be included in RDFs, geolexica.org pages, etc.

The first question is how to name them. "Notes" is already taken. Perhaps "comments" is a good name for its conciseness, but I guess we may have other type of public comments in future. Other candidates are "internal notes" and "maintainer notes", but maybe someone has a better idea. I'll be calling them "comments" for the rest of this entry.

The second question is if these comments should be a collection of pure strings or a collection of some kind of structured data (body, created at, author, type). The latter is an especially good idea if we consider adding some automated comments in future like "X edited this concept on DATE". For your information, IEV spreadsheets contain comments which are going to be imported, and they are composed of date, body, and author. Perhaps we can turn them into a plain text, but I'm not sure of that.

The third question is if these comments should be associated with concepts, localized concepts, or either. Comments in IEV spreadsheets are clearly meant to be associated with localized concepts, and I suppose that we should attach them to localized concepts too, but there are not many of them, so if someone has some strong arguments for storing them at concept's root level, then perhaps we can merge them or something.

[ErikStubkjaer41]

To illustrate the issue, in the Cadastre and Land Administration Thesaurus (CaLAThe) at http://cadastralvocabulary.org we have a (non-public) free text Change Note: , which could be e.g. 'Established with version 2. Definition added with version 3.' A problem recently identified is, that changes can be made without additions to the Change note. These additions are an extra effort. A structure like (body, author, date, concept, concept model item) , where 'concept model item' could be Definition or Broader or.. could account for whatever was changed. Would this be too clumsy? resource demanding? (One of my first comments; be gentle with defects :-)

[strogonoff]

@skalee perhaps those comments in fact consist of submitter, reviewer and control body notes? (Those notes will be captured alongside change requests, though can be exported simpler as comment notes if needed.)

@ErikStubkjaer41 It sounds like the idea is to see changes automatically summarized without having to describe them by hand? That’s a good point. This might concern Glossarist GUI more than concept model (@ronaldtse please correct me if I misunderstood the issue).

Data structures we use internally (a superset of concept model) allow detecting which parts of a concept were affected by a given change, making it possible for app interface to provide such a summary (although a justification will still have to be entered by hand alongside change request). Auto-summarization may not be implemented at first in app’s interface, though once it is it should work retroactively with past changes as well.

[ronaldtse]

IEV change messages

The IEV "INTERNALNOTES" (as it is called) are not notes but change messages. They look like this:

2017-02-20: Editorial revisions in accordance with the information provided in C00019 (IEV 102) - evaluation. JGO
2015-10-14: Addition of gender and part of speech to the French term/synonyms. JGO
2019-08-08: Editorial corrections: replacement of the () in the specific use; deletion leading article and incorrect exponent "e"; correction of the imaginary unit in the exponent from "i" to "j"; presentation "f", "g", "A" and "\phi" in italics; addition of a cross-reference to "analytic signal [IEV 702-04-52]". Validated with Erik Jacobson. JGO
2018-09-13: n corrected to <i>n</i> in the term. JGO

So each change message is composed of:

• Date
• Change description
• Author

Some INTERNALNOTE fields contain multiple change messages separated by a linebreak.

We can structure this information internally, I confirm that most (if not all) "INTERNALNOTE"s contain all this information and can be structured via parsing.

For the change description itself, it may be difficult to reverse create a machine-readable change unless we scrutinize every change message.

Machine-readable/generated changes

Thanks @ErikStubkjaer41 for raising this issue! As described by @strogonoff it is indeed possible to have the application automatically track changes and generate machine-readable changes. This way we can guarantee every single change to a concept or a localized term is verifiable and tracked.

We do need to differentiate between changes between a "concept" and a "localized term" because changes to both levels are possible and mean different things. In the IEC IEV for example, changes to localized terms are common (as seen in the examples above).

[ronaldtse]

The previous message did not however address @skalee 's original need:

We need to enhance concept model with some kind of internal notes (maintainer comments). These internal notes are meant to be edited and read by glossary maintainers

@ReesePlews has previously indicated that they do need maintainer notes per concept/localized term. These are not necessarily change descriptions but of a more ad-hoc nature. So "internal notes" are still necessary. As suggested by @skalee , the word "comments" may be acceptable.

We also have to accept free-text change descriptions in addition to machine-readable change descriptions.

[strogonoff]

@ronaldtse internal notes and remarks—any content that belongs neither to normative registry data itself, nor to CR (justification/reviewer notes/control body notes)—looks related to project management. We should probably consider whether a generic PM system should take care of this. PM specifics could wary on per organization basis and in simplest case be notes and comments as described here.

(my point is probably not directly related to concept model, I don't mind if it has that, but rather to our internal registry architecture)

[ronaldtse]

internal notes and remarks—any content that belongs neither to normative registry data itself, nor to CR (justification/reviewer notes/control body notes)—looks related to project management

Agree. This relates to the registry system indeed since these are probably "management notes" if they are not related to "changes".