Level of information in config.yaml files

[ErinWeisbart]

I'm wondering if the config files should be as streamlined as possible or if they should include as much user-friendly information as possible or somewhere in between. If streamlined, will detailed information live elsewhere? If so, where? And does it make sense to write it or at least take notes there as we go?

e.g. streamlined:

core:
  compartments:
      - Cells
      - Nuclei
      - Cytoplasm

verbose:

core:
  compartments:
  #list all compartments with profiling features measured in experiment
  #standard cell painting uses Cells, Nuclei, Cytoplasm
  #experiments with SABER also can include Mito, Golgi
  #names can be derived from .csv files found in workspace/analysis
      - Cells
      - Nuclei
      - Cytoplasm

in-between:

core:
  compartments:
  #list all compartments with profiling features measured in experiment
      - Cells
      - Nuclei
      - Cytoplasm

[ErinWeisbart]

(filling in the details/documentation as we go helps me to make sure I'm really understanding things)

[gwaybio]

(filling in the details/documentation as we go helps me to make sure I'm really understanding things)

Then let's do it!

We can always change things later

[gwaybio]

I'd say err on the side of verbose. Also perhaps consider a blend. Add documentation to the config file but maybe there could be a companion document describing how to fill out the config file.

I think a scientist with your skillset is the target audience/users for this code, so we should follow your intuition here.

[ErinWeisbart]

We'll move forward keeping actual config file streamlined and create corresponding verbose config documentation file to be written as we go.