Investigate adding optional labels to interface descriptions

[edwardchapin]

In existing ICDs which include software components (e.g., TMT.SEN.ICD.07.039), individual interfaces have unique tags along with their description, e.g.:

[INT-SUBSYSX-SUBSYSY-0100] SUBSYSY publishes rotation so that SUBSYSX can figure out its orientation.

These labels are chosen by hand, and may be referred to in other documents. If an additional field were added to the model files so that such labels could be provided, it would make it easier to (at least partially) transition from using word documents to the icd database.

[abrighton]

We already have requirements fields in the schemas for published items and commands received
and these are also displayed in the web and pdf output. For commands and published items you can
have a list of requirements (The value is an array of strings).

Is that what you were thinking of or do you want to be able to reference the requirements for subscribed items. for example, or be able to include a description of the requirements?

[edwardchapin]

These are actually different from the requirements you mention (although they have a similar format). These interface identifier numbers are clearly related to one or more requirements (which you have support for), but are specific to the ICD documents. See if you can dig up an example from the TMT docushare to see what I mean (like the one mentioned in the initial issue report).

[abrighton]

I couldn't find TMT.SEN.ICD.07.039 in docshare ( I found references to it).
Can you give an example of how you would use this in the schema?

[tmtsoftwareadmin]

I found it on my hard drive. I’ll send it to you in email.

On Mar 15, 2016, at 3:21 PM, abrighton [email protected] wrote:

I couldn't find TMT.SEN.ICD.07.039 in docshare ( I found references to it).
Can you give an example of how you would use this in the schema?

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub #26 (comment)

[edwardchapin]

Hopefully you've been able to find one of the software ICDs to see what they look like. Think of these identifiers as a section number in a given ICD document. The tricky thing is that these labels pertain to the ICD, and not a component's API (which is how the model files are organized). For example, you might think it is sufficient to label a telemetry item that is published by a component in subsystem FOO only with the identifier "42". Then, if subsystem BAR subscribes to that telemetry item, you could render its label in the FOO <-> BAR ICD view as [INT-FOO-BAR-0042]. The problem is that when we migrate the old word documents to the icd-db, there may have been a different interface from FOO to subsystem TCS that uses the same numerical value, like [INT-TCS-FOO-0042], which is actually different. So, my feeling is that you can't escape specifying the full ICD identifier (including both subsystem names) in the component-based model files, which is unfortunate.

[abrighton]

Yes, I have the example document now. I can see that there are many paragraphs starting with the identifiers like [INT-TCS-FOO-0042]. Currently you would just have to type these as paragraphs in the icd files. Were you thinking of a different way of entering these? For example an array of {id, description}?

[tmtsoftwareadmin]

You make a good case for why they might not be a good match for the model files. Maybe they should be in the boiler plate part of the ICD (I can't remember the name Scott R uses for this part of the document). Otherwise, I think we would need to add another model file with something like what abrighton has proposed and maybe link them to other sections like the links between publishers and subscribers.

[edwardchapin]

Yes, it's a bit hard to know what the right approach is here (hence, the "investigate" in the issue title :). At the moment, I'm just thinking it's a label you add as a field in the relevant model file. For example, a telemetry item already has a "name" and a "description" string. Just add another optional field called "identifier" which is a string that we manually input (and gets rendered in the ICD view).