BDQ Review - Actions and Comments: BDQ User's Guide

[Tasilee]

hese are a list of actionable items from the BDQ Review 2025-12-31 Review for @Tasilee, @ArthurChapman, @tucotuco, @chicoreus and @ymgan to discuss and address before resubmission of BDQ.

Because Issue #309 was too large; Action items have been extracted and Moved into sub-issues. This forms one of a number of sub-issues from #309.

Basics: Base documents under https://github.com/tdwg/bdq/tree/master/tg2/_build_review.

A number of issues may be duplicated across topics and are listed at the bottom of #309.

BDQ User's Guide (https://github.com/tdwg/bdq/blob/master/tg2/_review/docs/guide/users/index.md) (Arthur)

1. (Done) Stephen Formel (p. 21 Line 737) The guide seems to assume a large gap between users of tests and creators of tests. However, I think it’s natural for scientists to be curious about the details. The ‘users’ section should include more bridges to make it clear where the subject is covered in more detail in the guide. [Comment AC: I think I have addresses most of this in the rewrite. - Needs checking again once rewrite is approved]; (PJM): This has been addressed in the draft rewrite and incorporated into the users-header.md.
2. (Done) Stephen Formel (p. 21 Line 775 - example for this doc at Line 783)
   1. With help from Claude.ai, focusing on the users guide index
   2. What Works Well (Logical and Clear):
      1. Strong Structure: The document follows a logical flow from basic concepts (test types) to practical application (using the quick reference guide), which helps users progressively understand the system. Comment AC: OK
      2. Clear Test Type Definitions: The four test types are explained with helpful analogies: "Validation Tests can be thought of as fact-checking," "Issue Tests can be thought of as warning flags," "Measure Tests can be thought of as metrics," and "Amendment Tests can be thought of as suggestions for improvement."
      3. This can’t be clearly discerned from the TOC [Comment:AC - I am not sure I understand this - TOC has "Test Types at #2.1]; (PJM): I think this got effectively addressed in the draft through adding more explicit examples, making for more table of contents entries that get readers to the context, this is all incorporated into users-header.md.
      4. (Addressed in Draft Introduction document) Good Context Setting: The document effectively establishes that "Data do not have quality in the abstract; they only have quality with respect to a particular use," which is fundamental to understanding the framework.
      5. (Addressed in Draft Introduction document) This mantra should be brought to the surface. [Comment: AC - in the Introduction?]
   3. Areas That Could Be Clearer:
      1. (Done) Creating Tests: The guide focuses heavily on using existing tests but provides limited guidance on creating new tests. The workflow below would complement this gap. [Comment:AC - Covered by New Section in rewrite of User's Guide] (PJM): The user's guide should have minimal discussion of the creation of new tests, that belongs elsewhere, the users guide is about using existing tests @ArthurChapman make sure edits to users guide have minimal statements about creation of new tests. (PJM): Errors in the discussion of defining new tests in the draft have been fixed and text has been incorporated into users-header.md
      2. (Done) Use Case Connection: While it mentions that "Tests are assembled into Test suites (Policies) that assess the fitness of data for a specific use," it doesn't clearly explain how users should identify or define their use cases as a starting point. [Comment:AC - I think I have covered by New Section in rewrite of User's Guide] (PJM): This draft contained errors, but the text has been corrected and incorporated into users-header.md
      3. (Done) Overwhelming Detail in Section 3: The Quality Control vs Quality Assurance discussion, while thorough, might overwhelm users who just want to understand how to apply tests practically. [Comment AC: Addressed in rewrite] (PJM): Sounds like a don't fix, the detail is there on purpose, this is a very important point for users to understand. May need some rewriting, but the depth and detail are important in this guide. AC: The rewriting in the Draft was to make more "user friendly" - not important information left out (PJM): Reorganization in the Draft helped a lot in separating out the detail, but introduced errors, these were fixed and the corrected text incorporated into users-header.md. The detail is there on purpose, but should be much more readable now. AC: Happy with the final rewrite now.
      4. (Won't Fix) This is a key user group that could be either the ‘early majority’ of adopters, but without clarity would more likely become the ‘late majority’``[Comment AC" Not sure what I need to do with this] (PJM): Likewise.```
      5. (Done) Parameter Usage: The parameter example with depth measurements is technically correct but quite specific - a simpler, more universal example might be more accessible. [Comment AC: Different example used with fuller explanation] (PJM) Probably should be a don't fix, this example was very specifically chosen for this purpose. Perhaps use new text as a second example, but retain the original. AC: Reviewers had trouble understanding the example - I added a more easily understood example which I think covers it. If original stays - it needs a rewrite; (PJM) text in draft entangled normative and non-normative material in a normative section, untangled this, expanded upon both examples to make it clear what the examples are intended to communicate, aligned examples with previous results section, this should be much clearer now. Looks good now - but I have added some more corrections to text by PJM
3. (Done) Wording may need review to add "Automatically" Stephen Formel (p. 26 Line 972) Section 2.3: Databases of record SHOULD NOT automatically alter data based on Assertions made by Amendment Tests without human evaluation of the proposed changes. (PJM): Clarifying text from the draft added with revisions to users-header.md, should be much clearer now. AC:: Good`
   1. (Done) This maybe could be softened by pointing out interpretations as suggested amendments. [Comments AC: Addressed in rewrite] (PJM): This should not be softened, the word to emphasise is automatically, it is very dangerous to have code automatically change data in databases of record without human review, such actions are very likely to introduce errors. If anything this statement should be strengthened, not softened. AC - see comment above. (PJM) reorganization in the draft further confused issues, but placing section 3.3 Amendments Propose Changes at a high level, but following directly after 3.2.3.5 Amendment Test Reports, very helps the flow and clarity. Draft text made the choices expresssed by the repeated MAY clauses less clear, split these back out and emphasised **propose changes**, **not** and **automatically** in this section which clarify, similarly moving the block on amendments and uncertanty into a 3.3.1 helps clarify the flow and untangle normative/non-normative statements. AC: Happy with your last rewrite, PJM
4. (Done) Stephen Formel (p. 26 Line 978) Section 2.4.1 sentence should not have meter annotation: So, a value of dwc:minimumDepthInMeters of 2000m would be NOT_COMPLIANT in this case, while with the default value for that parameter (11000), it would be COMPLIANT. [Comment AC: Addressed in rewrite] (PJM): Corrected in expanded example for parameters worked into users-header.md AC: Looks Good
5. (Done) Stephen Formel (p. 26 Line 978) Section 3: This is probably the most critical section for the user to connect with the challenges and theory that have driven the development of this standard. However, it is dense and confusing. The definitions of QA and QC are confusing because they feel too similar. If the users don’t understand the nuances and differences, then they might become frustrated in trying to understand and learn the standard. [Comment AC: Agreed - addressed in rewrite - simplified and split up]
   1. (Done) In Quality Control (QC), Tests are used to identify data that are not fit for particular uses, with the goal of improving the data quality. [Comment AC: Definition simplified in rewrite]
   2. (Done) In Quality Assurance (QA), data are evaluated for fitness for use (i.e., whether they meet the requirements of specific operational tasks) and are filtered accordingly so that only data that are fit for use are included. [Comment AC: Definition simplified in rewrite]
   3. (Done) This section has something funky grammatically and maybe is just confusing: The keys for applying Data Quality Reports to improvement of databases of record is identification of focused areas for data cleanup projects, and identification of places where data quality problems may be reduced by improvements to workflow processes or user interfaces for entry and manipulation of data. [Comment AC: Simplified in rewrite]
   4. (Done) Also confusing: For example, splitting a single free text field into a controlled vocabulary field and a free text field for further elaboration, a data cleanup project to map all existing values onto a controlled vocabulary, and then changes to user interfaces to reflect the split into a controlled field and associated remarks. [Comment AC: Definition simplified in rewrite]
6. (Done) Stephen Formel (p. 26 Line 1009) Section 4: Confused by this example at the end of the section
   1. (Done) These include ways to identify the Test (Label: - the brief human readable means for identifying a Test (e.g. VALIDATION_BASISOFRECORD_NOTEMPTY); skos:prefLabel: - the human readable label spelled out in words; Versioned IRI: - the means for software to identify the Test). [Comment AC: Two additional examples added in rewrite to make it clearer what was being described] (PJM) incorporate into users-header.md along with further clarification by separating out the three means to identify a test as bullet points with additional explanation of the purpose of each. AC: Looks good