How to document ADaM & DISC terms

[donyunardi]

Hi @insightsengineering/nest-core-dev @insightsengineering/nest-sme,

I am creating this discussion to create consistency and eliminate confusion regarding what to quote and what not to quote in package documentation for CDISC-related terms. Additionally, I want to record the decision in case we need to revisit this.

We have already had several discussions on this topic:

• https://github.com/insightsengineering/coredev-tasks/issues/492#issuecomment-1899654808
• reduce the amount of spelling issues / WORDLIST goshawk#197 (comment) (please read)
• https://github.com/insightsengineering/coredev-tasks/issues/492#issuecomment-1901202835 (please read)

The current approach are:

To Quote

• dataset name (i.e. ADLB, ADSL, DM, etc)
• variable or column name from dataset (i.e. PARAMCD, AVALC)

Don't quote

• Acronyms, i.e. CDISC and ADaM

Can I please hear everyone's opinion on this?

[edelarua]

I think this makes sense! I would add that I think other code-related terms like package & function names should also be quoted.

[donyunardi]

I would add that I think other code-related terms like package & function names should also be quoted.

I agree. I believe this is what we're currently doing as well for the teal framework packages.

[m7pr]

Yes, in here (the second comment that @donyunardi asked us to read) I motivated what I did quote when doing a documentation overview in May 2023.

This is a challenging process to unify multiple packages written by various developers across a couple of past years. I needed to create one form of quoting for more than one repo. I decided that we should quote packages, functions, parameter names, objects and data structure names.

[lcd2yyz]

One more detail is to make sure to differentiate between an acronym/concept vs a variable/parameter/argument.

In reference to the example from @m7pr

Conceptually, LOQ is an acronym for "limit of quantification". So the phrase "LOQ flag" or "LOQ legend" should NOT be code-quoted. Only LOQFL should be quoted, because it's referring to the name of a variable.

Similarly, if referring to a statistical method, the name should NOT be code-quoted. However, if the name of the method is to be passed into a function as an argument option, then it should be shown in code-quote format. Consider the following example:

To compute statistical correlations, users can chose between various methods such as Pearson or Spearman, by passing in options like pearson or spearman in to the methods argument.