Why Model Documentation Is Part of the Dosing Intervention
A dosing model can be analytically sound and still be used incorrectly if its intended use, inputs, or outputs are unclear. A clinician needs to know which patients and decisions the model supports, what information to verify, and what a recommendation does—and does not—mean. A system administrator needs enough detail to configure the service, validate incoming data, and identify the deployed version. Documentation is therefore not an afterthought to the model: it is part of the interface between model behavior and clinical action.
The goal is concise, actionable documentation, not a second technical report. It should distinguish what the model was designed and evaluated to do from what an individual user may hope it can do. In particular, documentation should not imply that a prediction guarantees a clinical outcome or replaces clinical judgment. The earlier material on analytical validation, external validation, and change control informs what evidence and release details should be summarized; this tutorial focuses on how to communicate them for use.
A Documentation Structure That Follows the Decision
Organize documentation around the path from a clinical question to a model output and its interpretation. A concise top-level guide can link to a more detailed technical specification, but it should contain enough information to prevent a user from having to infer the model’s boundaries. A practical structure is:
- Intended use: name the supported clinical decision, eligible population, care setting, and intended user. State what the model does not support where that boundary could be misunderstood.
- Required inputs: list each variable, its definition, units, expected source, relevant time window, and whether it is mandatory. Explain validation, missingness, and stale-data behavior.
- Model assumptions: summarize assumptions that affect whether the output applies, such as the population represented by the model, the meaning of recorded measurements, and any conditions required for the prediction.
- Outputs and interpretation: define the recommendation and any accompanying prediction, uncertainty measure, alert, or status. Give units and explain how the output should inform—not dictate—the clinical decision.
- Limitations and escalation: identify important unsupported situations and specify what to do when inputs are outside bounds, the output is unavailable, or the case does not fit the intended use.
- Version and operations: identify the model and software release, configuration, effective date, and any dependencies needed to distinguish deployed behavior and support reconstruction.
These elements are connected. A statement of intended use defines which inputs and assumptions matter; those determine what output is meaningful; and the version information identifies which specification applies to an actual recommendation. If any link is missing, users may fill the gap with an assumption that was never evaluated.
Specify Inputs and Assumptions So They Can Be Checked
A variable name alone is rarely an adequate input specification. “Weight,” for example, does not tell a user whether the model expects kilograms or pounds, which measurement to use, or how old that measurement may be. Document the operational definition, units, source, and timing. If values are transformed before use, describe the transformation or point to a controlled technical specification. Make explicit whether the service rejects, flags, or substitutes a value that is missing, implausible, or outside the supported range. Never leave a safety-relevant fallback implicit.
Assumptions should be stated at the level needed to judge applicability. “The model assumes the data are correct” is too broad to guide anyone. Prefer specific statements, such as “the recorded administration time is assumed to represent the actual infusion start time.” If a condition is necessary for a particular interpretation, say what happens when it is not met. Do not present an assumption as a verified fact: for instance, a model that was evaluated in one care setting is not thereby established as valid in every setting.
For clinicians, assumptions should connect to observable checks: confirm that the measurement is recent enough, that the patient fits the stated population, or that the relevant administration history is available. For administrators, document machine-checkable rules where applicable: accepted units, allowed value formats, required fields, and the behavior on validation failure. Human-readable guidance and technical rules should agree; otherwise, a user may be told to proceed when the software blocks the request, or vice versa.
Worked Example: Turning a Vague Intended Use Into a Usable Statement
Suppose a hypothetical model supports dose review for adults receiving the fictional medicine QX-4 in an inpatient service. The draft description says only, “Predicts exposure and recommends a dose.” That wording does not identify which adults, what decision, or what the prediction means.
A more useful version-specific statement is: “For adult inpatients receiving QX-4 under the hospital’s standard intermittent-infusion protocol, this service estimates the next-interval exposure from the recorded dosing and concentration history and displays a candidate dose for clinician review. It is not intended for pediatric patients, outpatients, or dosing during extracorporeal therapy. The treating clinician remains responsible for reviewing the patient record and deciding whether to act.”
This revision names the population, setting, decision context, input-history dependency, and excluded circumstances. It also distinguishes a candidate dose from an automatic order. It does not claim that the prediction guarantees a target exposure or improves an outcome; those claims would require supporting evidence and a clearly defined context.
Write for Two Audiences Without Creating Two Versions of the Truth
Clinicians and administrators need different levels of detail, but both documents must describe the same release and behavior. A clinician-facing guide prioritizes eligibility, input review, output meaning, and actions when the recommendation is not applicable. An administrator-facing specification prioritizes interface contracts, data mappings, validation rules, service dependencies, and release identification. Both should refer to a common controlled model and configuration version rather than repeating potentially inconsistent values in separate informal documents.
A useful administrator specification states, for each input, the source field, data type, unit, allowed values or bounds where defined, and response to invalid data. It should identify the model artifact and software build, configuration and reference-data versions, and relevant interfaces. It should also describe expected status codes or user-visible messages for rejected inputs and unavailable predictions. These details support implementation and troubleshooting; they do not authorize administrators to change clinical assumptions or dosing logic outside the approved change process.
A useful clinician guide avoids implementation detail that obscures decisions. It should explain the output labels in plain language, provide units, distinguish a prediction from an observed measurement, and state which patient-specific factors require review. If an uncertainty interval or confidence indicator is displayed, define what it represents and how it should affect interpretation; do not imply that it removes clinical uncertainty. When the service cannot produce a supported recommendation, explain that absence of an output is not itself a dose recommendation.
Worked Example: Documenting an Input Contract
For the same hypothetical QX-4 service, suppose the prediction requires the administered dose, infusion start time, and a measured concentration. A concise input table in the controlled technical specification could read as follows:
| Input | Definition and unit | Source and timing | Handling rule |
|---|---|---|---|
| Administered dose | Amount actually given, in mg | Medication administration record for each relevant dose | Required; reject a missing or nonnumeric value |
| Infusion start time | Date and time, with time zone | Recorded administration event | Required; reject an unparseable timestamp |
| Measured concentration | QX-4 concentration, in mg/L | Laboratory result collected within the service’s supported sampling window | Required; flag a result outside the specified window rather than silently substituting it |
The table is useful only if the sampling window and any numeric bounds are defined in the controlled specification and implemented consistently. If, for example, the approved window is 2 to 12 hours after infusion start, the documentation should state those limits and the service should apply them using the same time basis. A statement such as “recent concentration required” would not let a clinician judge recency or an administrator test the rule.
The example also shows why data provenance and timing belong in the input definition: a valid-looking number can still be inappropriate if it belongs to another dose or was collected outside the intended window. The model should not silently treat an invalid or ambiguous value as valid.
Interpret Outputs, Limitations, and Release Details
Output documentation should define each displayed quantity and its role. If the service displays a predicted exposure and a candidate dose, label each distinctly and give units. State whether the candidate is a model-generated option requiring review, a dose range, or an alert. Explain which additional clinical information is not represented, and identify circumstances in which the output should not be used. A limitation is most useful when it gives a practical response: verify the input, seek specialist review, use the established non-model pathway, or do not proceed through the service.
Document limitations precisely rather than using a generic disclaimer. Examples include populations not represented in evaluation, unvalidated measurement methods, unsupported administration patterns, or dependence on complete dosing history. Do not turn an absence of evidence into a categorical claim that the model fails in every such case; state that use is outside the evaluated or intended scope. Similarly, do not use a broad disclaimer to excuse an unclear or unsafe operating procedure.
Version details should let a reviewer distinguish recommendations made under different releases. Record an immutable model identifier or artifact version, application or service build, configuration version, effective date, and the relevant input-schema version. Where applicable, identify the data or reference component version that can alter behavior. A user-facing version label should map unambiguously to these records. Version documentation complements the audit trail: the version says what was deployed, while the audit trail helps reconstruct which version and inputs were involved in a particular recommendation.
The right level of detail depends on the audience, but the information should be internally consistent and controlled. A short clinician summary can link to a fuller technical specification and approved operating procedure. A release note can summarize what changed, while the current guide states the current behavior. None should contradict the other, and none should rely on an undocumented verbal explanation for a safety-relevant rule.
Justifying the Documentation Chain
The structure above is not merely a convenient checklist. It follows from what must be known to interpret a recommendation. First, intended use establishes whether the case is in scope. Second, input definitions and assumptions establish whether the data satisfy the conditions under which the output is meaningful. Third, output definitions explain what the result represents and what action it can inform. Finally, version details establish which model and operational rules generated the result. If one of these links is absent, the recommendation cannot be interpreted reliably from documentation alone.
Check the patient, setting, and decision against the stated intended use.
Check that required inputs meet their definitions and that relevant assumptions are plausible.
Use the documented meaning, units, limitations, and clinical review guidance.
Use the model, software, and configuration versions to establish which documented behavior applies.
Worked Example: Explaining an Output Without Overstating It
Imagine the hypothetical service displays “predicted next-interval exposure: 42 mg·h/L” and “candidate dose: 180 mg.” The intended-use guide defines the exposure interval and units, says that the candidate dose is for clinician review, and warns that the prediction depends on accurate administration times and the stated input window.
A sound interpretation is: “The model predicts an exposure of 42 mg·h/L for the specified interval from the supplied history and proposes 180 mg as a candidate dose for review. Confirm that the administration record and concentration timing are correct, assess relevant clinical information not represented by the model, and follow the local process before acting.” The numeric values are hypothetical and illustrate documentation wording, not dosing advice.
An unsound statement would be: “The patient will have an exposure of 42 mg·h/L, so give 180 mg.” The first clause converts a prediction into certainty; the second turns a candidate into an instruction and skips the required review. Documentation should make those distinctions explicit in labels and interpretation guidance, not leave them to inference.
Common Documentation Failures and Alternatives
Common failures include naming inputs without units or time windows; describing the model as “for all patients” when its intended population is narrower; presenting a recommendation without defining its status; and listing limitations without telling users what to do. Another failure is documenting only the model algorithm while omitting the deployed configuration that affects behavior. A polished technical report does not fix an ambiguous clinician workflow, and a brief quick-reference guide does not replace implementation rules.
Documentation also needs maintenance. A change to a model artifact, input mapping, display, or supported population can make existing text misleading. Release review should therefore check that user-facing and administrator-facing statements remain aligned with the actual deployed behavior. If a requirement cannot be stated precisely, that is a signal to clarify the behavior itself, not to hide ambiguity behind broader wording.
Different documents serve complementary purposes. A technical model report explains development and evaluation methods in depth. A clinical user guide supports interpretation and use. An administrator specification describes system interfaces and configuration. A standard operating procedure defines local workflow and responsibilities, while release notes describe changes between versions. These are alternatives only when deciding where a detail belongs; they are not substitutes for one another. Core facts—especially scope, input definitions, output meaning, and version identity—must remain consistent across them.
Documentation has limits. It cannot make an unsupported use appropriate, guarantee correct data entry, or replace validation, monitoring, governance, or clinical oversight. Its contribution is narrower and essential: it makes intended behavior and boundaries inspectable, so users can recognize when a recommendation is relevant and administrators can identify what the service is supposed to do.
Check Your Understanding
Answer each question, then compare your reasoning with the solutions.
- A guide says a model uses “recent weight.” What additional input details should be documented?
- Why should a candidate dose be distinguished from an automatically authorized dose?
- A service accepts a concentration without recording its collection time. Which documentation and operational issue does this create?
- Name two version details that help distinguish deployed behavior, and explain why a user-facing label must map to them.
- How should documentation handle a patient group that was not represented in model evaluation?
Solutions: (1) Specify the weight definition, units, expected source, and acceptable age of the measurement; state how missing, implausible, or stale values are handled. (2) The distinction tells clinicians whether the output informs a decision or constitutes an authorized action; blurring it can bypass intended clinical review. (3) The input contract lacks a timing variable needed to assess applicability, and the service cannot reliably enforce any sampling window; documentation and implementation should define and validate collection timing. (4) Examples include the immutable model artifact identifier and the application build or configuration version. The user-facing label must map unambiguously to controlled records so the behavior behind a recommendation can be identified. (5) State that the group is outside the intended or evaluated scope, avoid implying established performance there, and provide the locally approved alternative or escalation route.