Use AI to Help Document Applications — With Human Review and Guardrails

This chapter explains how AI can help create and maintain Application Documentation, and the guardrails needed to use it safely.

How AI Can Help

AI can reduce the effort of documenting Applications in several ways:

• Drafting documentation from source code, configurations, deployment scripts, tickets, test results, and existing notes.

• Constructing source code documentation, such as module and component descriptions, code comments, and API references, directly from the code, so that code-level documentation keeps pace with the code it describes.

• Creating a baseline Application Documentation Template from these best practices and the enterprise’s own inputs, as described in the chapter “Establish and Use an Application Documentation Template.”

• Finding gaps by comparing an Application’s documentation with the template and highlighting missing or thin sections.

• Detecting staleness by comparing documentation with recent changes and flagging content that may no longer be accurate.

• Summarizing and restructuring existing documentation into the template’s structure.

• Answering questions about an Application from its documentation, which also reveals where the documentation cannot answer them.

Establish Guardrails for AI-Assisted Documentation

AI-assisted documentation should be governed by the following guardrails:

• Human review before publishing. AI-generated or AI-revised content is reviewed and approved by a knowledgeable person before it is published. The Application Manager remains accountable for its accuracy.

• Keep secrets and sensitive content out of AI tools. The values of Security Secrets must never be submitted to any AI tool, approved or not. Sensitive code and sensitive data must never be submitted to AI tools that the enterprise has not approved for that purpose.

• Use enterprise-approved AI tools. Use only AI tools approved under the enterprise’s AI governance, with appropriate data handling.

• Mark AI-assisted content. Record where content was drafted with AI assistance, so that reviewers know to check it with particular care.

• Never let AI invent facts. Instruct AI tools to flag missing information rather than fill it with plausible guesses, and record anything that cannot be verified as a Knowledge Debt Item rather than publishing it.

Document and Share AI Usage

Record in the Application Documentation, or in its change history, which content was produced or revised with AI assistance, who reviewed it, and when.

Best Practice: Use AI to Help Document Applications, with Human Review and Guardrails

It is a best practice to both establish and document the solution for AI-assisted documentation: use enterprise-approved AI tools to draft, check, and maintain Application Documentation, require human review before anything is published, keep Security Secrets out of all AI tools and other sensitive content out of unapproved ones, and record where AI was used.

Benefits: Used with guardrails, AI makes thorough documentation far cheaper to produce and maintain, removing one of the most common excuses for not documenting. Human review and recorded usage keep accountability with people and stop AI from introducing confident errors into the documentation that people, and other AI tools, will later rely on.

Connections to Related IF4IT Practices and Inventories

The Enterprise AI Governance Best Practices addresses the approval and governance of AI tools. The Best Practices for Making Legacy Data Semantic and AI-Ready addresses preparing enterprise knowledge for use with AI.