Author Topic: What is the best way to model document references?  (Read 1452 times)

mse

  • EA User
  • **
  • Posts: 303
  • Karma: +1/-0
    • View Profile
What is the best way to model document references?
« on: May 24, 2024, 09:38:05 pm »
I am importing PDFs, word document or other files into the model so that I can track the references we are using. I want to generate a report with a table listing like this:

ReferenceSummaryVersionTitle
Ref. [1]SysML Standard1.7OMG Systems Modeling Language (OMG SysML™)
Ref. [2]DO-178CSoftware Considerations in Airborne Systems
and Equipment Certification

It seems I can do this in many ways. I could go with Artifact, and give it a name (for the summary column), alias (for the "Ref. x" column), notes for the title column, and version using the Version column.

I am using Artifact option because when I drag and drop a PDF onto a diagram, I am presented with Artifact (internal) or Artifact (external) in a context menu. This seems to work, and I can also generate a report, but is there a better way? The only reason I ask is because of that first column Reference. I have to use the Alias field of the element, but I'm not sure if that's the proper use of Alias, even though it could be anything.

I would also like to reference the artifact from other Notes fields. This may be stretching EAs capabilities a bit, but I want to see the reference text update in the notes if [Ref. 1] for example is deleted or changes (just like maintaining a list of citations in academic papers).
« Last Edit: May 24, 2024, 09:51:22 pm by mse »

ea0522

  • EA User
  • **
  • Posts: 134
  • Karma: +5/-0
    • View Profile
Re: What is the best way to model document references?
« Reply #1 on: May 28, 2024, 04:16:57 pm »
When using references like this, I tend to keep away from numbers.
For the list you present I would use e.g.:
Reference
[SysML] ....
[DO-178] ...

The advantage is that you don't have to wonder how to renumber when a reference is removed (or not used).
And I think it would be easier to keep the references unique.
Lastly, you can always use the correct reference in the text when referring to a document as it is not likely that a reference will change once it has been defined.

One last remark, you probably would even be able to sort the list of references based on the name of the reference.