ERM - When to link Module Artifacts versus Linking Base Artifacts

Modules in ERM are described really badly in the Knowledge Center and it causes so many misconceptions and problems!

I personally hate the way they talk about "Base Artefacts" and "Module Artefacts" - this is a hangover from the folks who came from DOORS 'Classic' and really hampers understanding the power of DOORS Next. The best way to think about this is that a piece of text is just an artefact, and it lives in, and is owned by, a project area. There are 4 ways you can aggregate or group artefacts:

 - Folders: this is actually pseudo-attribute on an artefact (nav:parent) and is set when you create or move artefacts around in the folder structure in the UI. Artefacts can only belong to one folder at a time because the pseudo-attribute can contain only one value at any time. It's a neat way to organise artefacts in the UI

 - embedding: I won't discuss this here as it's not relevant

 - Collections: a Collection is like a virtual "bag of stuff" but, unlike a real bag or DNG Folders, the same artefact can be put into multiple Collections at the same time. Collections are defined as Artefact Types in DNG for ease of management, but they are a separate thing in the OSLC spec and there are API services that let you manage and retrieve them. Under the hood they are a list of references to artefacts within the Project Area

 - Modules: a Module is best thought of as a "Collection with a Context" and this is what makes them so powerful in DNG. If you use the OSLC API and ask for all Collections, you'll get back Modules as well, and you can see that, just like Collections, they are a list of references to artefacts. However, Modules extend the Collection concept by also adding a Context for each of these references that then identifies the order, indenting, and styling applied to the artefact within the context of that Module. The Context also remembers the link ends, tags and Comments made for that artefact in that Module's context.

This is what makes Modules powerful, and allows you to do some very cool (and very confusing!) things:

 - the context keeping track of the order, indentation and styling of artefacts makes it great for making the contents look and feel like a document, and this is the most common reason people create Modules

 - a Module's context means that the same artefact in two different modules can be in different positions, at different levels of indentation, and even styled in one module to show as a numbered heading but in another as regular text (not to be confused with creating a Heading Artefact Type). You can even add the exact same artefact into a Module multiple times and style/indent it differently. This is often done by mistake, but I've used this deliberately to create "Executive Summary" sections or Appendices for requirements that need calling out in some way in a document

 - a Module's context also means that tags and Comments made in one module will not show up in any others. By being careful about where you apply tags and comments, you can make sure they are seen EVERYWHERE (add at artefact level), or just within that specific Module. This is great when you have different versions of a document, or a subset of requirements reused across different places and your comments (such as within a review) should only apply in one specific Context.

 - finally a Module's context means that visibility of the ends of Links can be controlled. Again, many people do this by accident, but it's super powerful when used deliberately. A great example is where you have a set of requirements that get reused across several subsystems or components. If you set up the upward traceability to stakeholder requirements at the artefact level, then no matter which component you add them to you'll see where they were derived from. But if you set up downward traceability to test cases at the module level, then the test cases and results will be specific to that component only. Even better, you can then report on every component where that requirement has been used, and the current individual status of the testing or design process for each of the subsystems or components.

They often forget to select the Module, before the Artifact when creating a link and end up inadvertently creating a 'Base Artifact' link.

These show up with the famous blue arrow next to the link icon in Views, but are excluded by /jrs when put into a report, hence wasting their effort.

Short of better education, has anyone found a better way to address this problem??