Hi Geert,
I don't have a good answer for you, but I'd like to
hear myself talk for a while offer some suggestions.
My background is in defence contracting, which is a high-QA environment to the point where it's more important to get it right, and to prove that it's been done right, than to streamline the QA processes. So that's where I'm coming from.
It's good practice to separate syntax checking, which a machine can do, from content checking, which requires understanding. Reviewing should focus primarily (exclusively, really) on the latter. If you're working with documents, an author is expected to spell-check, format and structure their document correctly before sending it out for review; asking a team of subject matter experts to check a document for spelling errors is just a waste of skills, time and money.
So a model validator should be seen as a tool used by the modeller, not by the reviewer. Once the validator OK's a model, it can be sent out for review. Now in your case you're doing both the syntax checking and the content checking, but it's still a good idea to keep them separate in your mind.
When it comes to storing and sharing review remarks, a cardinal rule is that the CI (configuration item under review) must not be altered in any way by the review. This means that any way of working which involves creating elements in the reviewed model -- adding notes to CI diagrams, setting properties in CI elements, adding connectors to CI elements -- is out. The review
suggests changes, but only the author
makes changes. This might be less of an issue when there is only one reviewer, but as soon as there are more than one it becomes impossible to keep track of what each reviewer actually saw, if you allow the review process to make changes to the CI.
(There is an alternative way of working with reviews which involves making changes in a local copy of the CI, and submitting diffs as a result of the review. Possibly something like this could be achieved in EA using baselines and a multi-project setup, but unless each CI model is completely self-contained it gets pretty complicated pretty quickly.)
The doctrine of no CI change means EA's maintenance items are out. They're not much use anyway, it's far too hard to navigate them in anything but a single-package-single-diagram-two-element scenario, aka the real world.
In general, I feel EA's functionality in this area (indeed, the whole collaboration area) is a bunch of half-baked ideas, nothing coherent that can actually be used. I haven't dived deep into the team library, but I note that
the manual says it "can be used to conduct model reviews from any number of perspectives, including walk-throughs, formal model reviews, or ad-hoc reviews" -- but there's no laid-down process for how to do any of those things. Not even an outline. So it comes across as sales-pitch, demo-level stuff.
So it's roll your own, but I think there's a pretty handy way to do it: in-model RTF documents with hyperlinks.
Set up a package structure for reviews, in a separate root node. The substructure obviously depends on how the rest of your project is set up, but at the lowest level you'll want one package for each review of a particular CI. So the package at this level would be called something like "Review of model 'bla bla bla', 2020-05-26".
In this package, each reviewer gets one RTF document (document artifact). You can create a template for these; it's basically just a simple table.
The reviewer adds their remarks to their document, adding hyperlinks to diagrams/elements where appropriate. (If you want you could modify your validator to direct its output to such a document too, of course.) Hyperlinks are light and one-way, so the CI model is not changed by the review. Importantly, the hyperlinks are only there to ease navigation. The actual remark is expressed in free text.
In addition to allowing the reviewer to write free text, they can work on their remarks in the context of their review, not in the context of the CI model, and not tied to some half-baked "discussion" structure. This is important.
Then on top of this there is the question of what to do with the remarks once the review is completed. Some remarks should be implemented, others could be rejected. You could add a column for that to the review template, or you could collate all reviewers' remarks into a separate document where the author (or whoever makes the decisions) can record their decisions.
I really think document artifacts with hyperlinks are the best way to do reviews in EA. None of the built-in functions are going to work without a lot of customization, and while the artifact way will require some customization as well it's very simple to set up, to understand and to work in. The reviewer works from the project browser, but at the same time with a review focus and without making changes to the CI.
HTH,
/Uffe
