THE GITHTML FIELD GUIDE
Verify AI-generated documentation code examples before publication
A generated code example is an instruction readers may copy, so review it as carefully as a behavioral claim. Confirm that its APIs exist for the stated version, identify side effects, remove secrets, and test it only in an authorized environment. Clearly distinguish executed examples from illustrative pseudocode.
Define what the snippet is meant to prove
A short example cannot demonstrate every aspect of a feature. State whether it teaches syntax, validates a local transformation, or shows a complete integration. An illustrative JSON parser example should not quietly assume network credentials or access to a production bucket. Identify language and dependency versions from the project, then consult their primary documentation when behavior is uncertain. NIST's generative AI profile provides context for incorrect generated content; your practical safeguard is to verify the specific API and behavior rather than trusting fluent explanations around the snippet.
Review safety before execution
Read the whole example before running it. Look for filesystem writes, network calls, deletion, privilege changes, and hidden assumptions about the working directory. Placeholder tokens should be unmistakable and should not resemble working credentials. For an illustrative API request, explain whether it merely reads a resource or changes server state; do not infer safety from a friendly endpoint name. Ask for authorization before performing actions outside the documentation task. A snippet can be syntactically valid and still be unsuitable for a user's environment.
- Existence: confirm the functions, flags, and configuration keys are real.
- Context: state versions, prerequisites, inputs, and expected output.
- Effects: identify writes, requests, resource creation, and cleanup requirements.
Record the validation honestly
If a snippet was tested, record the command or procedure, environment, revision, and observed result. A successful run with one sample does not establish behavior for all inputs, so preserve relevant limitations. If execution was not appropriate, label the example illustrative and describe what remains unverified. Keep code as escaped text in the published HTML so opening the page does not execute it. The user runs generators and verification tools separately; gitHtml is the reading surface for the approved document, not a code execution environment.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.