Improve the metadata description structure

Why are we doing this?

Following a chat on 13/05/2025, the team recognised that it's unclear to users what 'good' metadata description looks like. Without good guidance, metadata description can lack detail for others to confidently understand and reuse a codelist.

The Clinical Informatics team use an issue template to structure and plan their codelist builds, which are now being copy-and-pasted to the metadata description, so that useful information is surfaced more visibly—especially for external users who may not look at the linked issue.

There were suggestions of automatically surfacing user actions from building codelists,(e.g. search terms, key incl/excl actions), but it's not clear what the typical user workflow is, best practice, or how to prompt users in a helpful (not intrusive) way.

The group agreed that until it's clear what good metadata looks like and how to encourage users to create good metadata for others users to review and want to reuse their codelists with confidence, the low-hanging fruit would be to provide clearer guidance and structure for users writing metadata descriptions.

How will we know when it's done?

• Metadata entry will include structured prompts or fields inspired by the Clinical Informatics issue template linked above:
  -- Specificity / Sensitivity
  -- Search terms
  -- Inclusion criteria
  -- Exclusion criteria
  -- Borderline cases
• The new layout or guidance will be tested with a small number of users to confirm it fits naturally into their workflow and improves clarity

What are we doing?

• Add structured prompts or placeholders to the metadata entry form to encourage inclusion of key information.
• Align these prompts with the Clinical Informatics team’s existing approach.
• Run lightweight user testing or feedback sessions to evaluate usability.
• (Optional/future) Begin exploring what a more automated or assisted metadata entry process might look like, based on user workflows.

Defining delivery tasks guidance

Start with the Clinical Informatics issue template linked in the issue and inspect the metadata entry form, whose file or entry point is not specified here. Review how the proposed prompts fit the existing workflow, then test the revised layout with a small group of users. Done means the form includes the listed metadata guidance and feedback confirms it improves clarity without being intrusive.