Ethical Documentation

Imagine this: A hospital implements a new AI system to help diagnose skin cancer. The marketing materials boast “99% accuracy!” The hospital staff, impressed by this number, begins relying heavily on the system.

Six months later, they notice something disturbing. The system misses diagnoses far more often with patients who have darker skin tones. Looking back at the documentation, they find a tiny footnote: “System trained primarily on fair-skinned populations. May have reduced accuracy for Fitzpatrick skin types IV-VI.”

Lives were at risk because critical information was buried where few would find it.

This isn’t just a documentation failure. It’s an ethical failure.

In this module, we’ll explore how your documentation choices aren’t just technical decisions—they’re moral ones. The words you choose, the limitations you disclose (or hide), and how you guide users can quite literally save lives, protect rights, and prevent harm.

Why AI Documentation Has a Higher Ethical Bar Than Your Toaster Manual

Let’s start with something we can all agree on: documenting an AI system requires more ethical consideration than documenting a toaster.

Why? Because unlike your toaster, which has predictable behavior (put bread in, toast comes out), AI systems:

• Make consequential decisions about people’s lives, opportunities, and rights
• Learn from data that may contain historical biases and prejudices
• Create complex, cascading effects in society that are hard to predict
• Operate with varying degrees of transparency and explainability
• Can cause harm at massive scale if misused or poorly designed

As the person writing the documentation, you become the critical bridge between the creators who understand the system’s inner workings and the users who will deploy it in the real world. You have the power—and responsibility—to prevent harm through your words.

“The thing that’s transformational about AI isn’t the technology itself, but how humans use it.” — Your documentation is the instruction manual for how humans will use AI.

Your Ethical Documentation Toolkit: 7 Elements That Matter Most

1. The Origin Story: System Purpose and Boundaries

Every superhero has an origin story that explains their powers and limitations. Your AI system needs one too.

What to include:

• The “designed for” statement: “This system is designed to predict customer churn for subscription businesses with 1,000+ customers” (not “This system predicts human behavior”)
• The “not designed for” statement: “This system is NOT designed for evaluating employee performance or making hiring decisions”
• Decision-making guidance: Clear instructions on whether the system should be used as a suggestion, a decision aid, or an automated decision-maker
• Human oversight requirements: Specific situations where human review is essential

The ethical payoff: Users understand exactly what the system can and can’t do, preventing dangerous mission creep.

Real-world example: A college admissions decision support system clearly states it’s designed only to identify candidates for further review, not to make final decisions, and requires admissions officers to document their reasoning when they disagree with system recommendations.

2. What’s in the Recipe: Data Transparency

Would you eat a meal if the chef refused to tell you the ingredients? Probably not. Users deserve to know what “ingredients” went into your AI system.

What to include:

• Data sources and age: “Training data includes customer transactions from North American retailers between 2018-2021”
• Collection methods: “Survey data was collected via opt-in mobile app surveys with monetary compensation”
• Representation facts: “Training data includes customers from 40 countries, with strongest representation (80% of samples) from North America and Western Europe”
• Known gaps: “The system has limited data from users under 25 and over 65”

The ethical payoff: Users can assess whether the system’s “ingredients” match their use case and population.

Data transparency in action: An emotion recognition system discloses that its training data consists primarily of posed expressions by professional actors rather than spontaneous emotions, helping users understand why it might miss subtle emotional cues.

3. The Fairness Conversation: Bias and Equity

Let’s be honest—no AI system is perfectly fair across all dimensions. Ethical documentation doesn’t claim perfection; it honestly discloses where biases may exist.

What to include:

• Demographic performance differences: “Accuracy varies by age group: 94% for ages 25-45, 88% for ages 46-65, and 79% for ages 65+”
• Testing across intersectional categories: “We evaluated performance across combinations of gender, age, and geographic location”
• Fairness definitions used: “We prioritized equal false positive rates across groups”
• Mitigation strategies: “To address performance gaps, we implemented balanced class weights and fairness constraints”
• Ongoing monitoring: “We conduct quarterly bias audits with updated testing datasets”

The ethical payoff: Users can take proactive steps to monitor and address potential discrimination.

Why this matters: A resume screening tool discloses that it has a higher rejection rate for applicants with employment gaps. This allows HR teams to specifically review these cases, protecting candidates with gaps due to childcare, health issues, or other legitimate reasons.

4. Setting Expectations: Performance Limitations

Every system has limitations. Ethical documentation doesn’t hide them in the fine print—it puts them front and center.

What to include:

• Accuracy ranges, not just best-case numbers: “Accuracy ranges from 92-97% in typical conditions, but drops to 60-75% when input images are low resolution”
• Common failure modes: “The system often confuses similar-looking product categories (e.g., muffins and cupcakes)”
• Environmental limitations: “Performance degrades in noisy environments above 70 decibels”
• Edge cases: “The system has not been validated for users under 18”

The ethical payoff: Users can anticipate problems and implement appropriate safeguards.

Honest limitations in practice: A financial fraud detection system explicitly states that it performs poorly on transaction patterns it hasn’t seen before, prompting banks to implement additional monitoring for novel transaction types.

5. Keeping It Real: Uncertainty Communication

AI systems don’t “know” things—they make probabilistic predictions. Ethical documentation helps users understand what those probabilities actually mean.

What to include:

• Confidence score explanations: “A 90% confidence score means that historically, predictions with this score were correct about 9 out of 10 times”
• Error rate contexts: “A 3% error rate means approximately 3 in 100 customers will be misclassified”
• Visualization guidance: “Red zones on heatmaps indicate areas with less than 80% confidence”
• Decision threshold recommendations: “For high-stakes decisions, we recommend a minimum confidence threshold of 95%”

The ethical payoff: Users make better-informed decisions about when to trust the system.

Uncertainty in action: A medical diagnostic support tool shows doctors not just the most likely diagnosis but also alternative possibilities with their probability ranges, reducing the risk of premature closure (fixating on an initial diagnosis).

6. The Bigger Picture: Environmental and Social Impact

AI systems don’t exist in a vacuum—they affect communities, environments, and societies. Ethical documentation acknowledges these broader impacts.

What to include:

• Resource requirements: “Running this model requires approximately 500 kWh of energy per day when processing 100,000 requests”
• Carbon footprint: “Estimated carbon footprint of 2.3 tons CO2 for training, 0.5 tons per year for inference”
• Labor practices: “Data annotation was performed by contractors paid at least 1.5× local minimum wage”
• Potential displacement effects: “This system may reduce demand for entry-level data processing roles”

The ethical payoff: Organizations can make holistic decisions that consider more than just technical performance.

Impact documentation example: A smart city traffic optimization system discloses that while it reduces overall congestion, it may increase traffic in certain previously quiet neighborhoods, allowing city planners to implement complementary measures.

7. Keeping Users Safe: Security and Privacy

Security vulnerabilities in AI systems can create serious ethical problems. Documenting them appropriately balances transparency with safety.

What to include:

• Known vulnerability types: “The system is susceptible to data poisoning attacks if adversaries can access the feedback loop”
• Privacy practices: “User inputs are processed locally and not stored on our servers”
• Security testing performed: “We conduct regular adversarial testing and red-team exercises”
• Responsible disclosure process: Clear instructions for reporting discovered vulnerabilities

The ethical payoff: Users can implement appropriate security measures and protect sensitive data.

Security ethics in practice: A facial recognition system documentation includes specific guidance on secure deployment, access controls, and audit logging to prevent unauthorized surveillance.

Documentation Frameworks: The Recipe Cards for Ethical AI

You don’t need to reinvent the wheel. Several standardized frameworks already exist to help structure ethical AI documentation. Think of these as recipe cards—they provide a structure, but you still need to fill in the details.

Model Cards: The Executive Summary

Developed by Google, model cards provide a concise overview of an AI model’s capabilities, limitations, and ethical considerations.

The structure looks like:

Model Details: What it is, who made it, when
Intended Use: What it's for (and not for)
Factors: Variables that affect performance
Metrics: How performance was measured
Evaluation Data: What data tested the model
Training Data: What data taught the model
Ethical Considerations: Potential risks and mitigations
Caveats and Recommendations: Usage guidance

Why they work: Model cards are concise enough (typically 2-4 pages) that people actually read them, while covering the critical information needed for ethical use.

Real-world example: Google’s BERT model card clearly explains that the model may reflect biases in its training data and should not be used for making predictions on text from very different domains without careful evaluation.

Datasheets for Datasets: The Origin Story

Proposed by Timnit Gebru and colleagues, datasheets document where datasets come from and how they should be used.

The key questions answered:

• Why was this dataset created?
• How was the data collected?
• Who collected the data?
• How was the data processed?
• What’s in the dataset (and what’s missing)?
• Who should (and shouldn’t) use this dataset?
• How should success be measured?

Why they matter: Many AI harms stem from problematic datasets. Datasheets create accountability and transparency around data origins.

Datasheet example: A face recognition training dataset datasheet discloses demographic imbalances and explicitly states it should not be used for developing systems deployed in regions with populations significantly different from the dataset composition.

AI Impact Statements: The Risk Assessment

Similar to environmental impact statements, these documents assess the broader effects of deploying an AI system.

What they typically include:

• Description of the system and its purpose
• Stakeholder analysis (who’s affected)
• Risk assessment across different dimensions
• Mitigation strategies for identified risks
• Monitoring and evaluation plans

The value they add: They shift focus from narrow technical performance to broader societal impacts.

Impact statement in action: Before deploying a predictive policing system, a police department publishes an impact statement identifying potential risks of reinforcing discriminatory patterns and detailing the oversight and auditing measures they’ll implement.

Writing in Practice: The Art of Ethical Communication

Frameworks provide structure, but your specific word choices and presentation decisions matter enormously. Here are some practical tips for ethical documentation writing:

Choose Your Words Carefully

The language you use shapes how users perceive and interact with AI systems:

• Say “predict” not “determine”: “The system predicts credit risk” not “The system determines creditworthiness”
• Use specific performance claims: “94% accurate on our validation dataset” not “highly accurate”
• Avoid anthropomorphism: “The model was trained to classify images” not “The model learns to see images”
• Name humans in the loop: “The system flags accounts for review by a compliance team” not “The system detects fraud”

The human difference: An AI recruiting tool that promises to “find the best candidates” creates different expectations than one that “suggests candidates for further review by hiring managers.”

Create Multiple Documentation Layers

Different stakeholders need different levels of information:

• Executive summary: 1-page overview of key capabilities and limitations
• User documentation: Practical guidance on day-to-day use and interpretation
• Technical specification: Detailed information for implementers and auditors
• Research paper: Comprehensive methodology for academic review

Why this works: It makes ethical information accessible to each audience while ensuring comprehensive documentation exists.

Layering in practice: A healthcare AI company provides clinical staff with simplified decision guides, while offering technical teams detailed model validity documentation and giving regulatory bodies comprehensive training data documentation.

Use Visual Ethics Communication

Some ethical concepts are better shown than told:

• Performance distribution charts: Show how accuracy varies across different groups
• Confidence visualization: Illustrate what different confidence levels mean
• Decision threshold simulators: Let users see how different thresholds affect false positives/negatives
• Input limitation examples: Show examples of inputs where the system performs poorly

The power of visual ethics: A credit scoring model provides a simulation tool letting loan officers see how changing various factors would affect the score, making the model’s behavior more transparent.

Common Ethical Documentation Dilemmas (and How to Handle Them)

Even with the best intentions, you’ll face tricky situations. Here’s how to navigate them:

Dilemma #1: “But If We Disclose That Limitation, No One Will Use Our Product!”

It’s tempting to bury unflattering information, but consider:

• The ethics angle: Hiding limitations that could cause harm is unethical and potentially illegal
• The practical angle: Undisclosed limitations will eventually be discovered, damaging trust far more than honest disclosure
• The solution: Frame limitations as boundary conditions, not flaws. “This system is designed and tested for X” is better than “This system doesn’t work for Y”

A balanced approach: An emotion recognition company discloses that its system is less accurate for people with certain facial features, while explaining the specific use cases where it remains reliable.

Dilemma #2: “Marketing Wants Us to Remove the Warning Labels”

When business pressures conflict with ethical disclosure:

• The ethics angle: Your responsibility is to users who rely on accurate information
• The practical angle: Misleading documentation creates legal liability
• The solution: Find a constructive framing that acknowledges limitations while highlighting strengths. “Best performance when used for X” rather than just “Poor performance for Y”

Making it work: Instead of vaguely claiming “AI-powered hiring,” a recruiting tool specifically documents which parts of the process use AI and which require human judgment, setting appropriate expectations.

Dilemma #3: “We Don’t Know Exactly How It Works”

When facing the “black box” problem:

• The ethics angle: Lack of understanding doesn’t remove the duty to document known behaviors
• The practical angle: You can document observed patterns even if you can’t explain the mechanisms
• The solution: Be honest about uncertainty while documenting empirical testing. “While the exact decision process is complex, our testing shows consistent patterns…”

Transparency about opacity: A deep learning system for medical imaging candidly states that while the exact features used are not fully interpretable, the system has been validated through extensive testing across diverse populations.

Dilemma #4: “No One Reads Documentation Anyway”

When facing documentation fatigue:

• The ethics angle: The duty to inform exists regardless of whether people choose to be informed
• The practical angle: Good documentation protects you legally and reputationally
• The solution: Make critical ethical information unavoidable in the user experience. Build it into onboarding, user interfaces, and decision points

Making ethics unavoidable: A facial recognition system requires users to complete a brief training that covers accuracy limitations across demographics before they can use the system.

Your Ethical Documentation Checklist: The Practical Tool

Here’s a simple checklist to ensure your AI documentation meets basic ethical standards:

✓ Purpose and Limitations

• Clear statement of what the system is designed to do
• Clear statement of what the system should not be used for
• Description of required human oversight
• Explicit limitations on autonomous decision-making

✓ Data Transparency

• Description of training data sources
• Demographic representation information
• Data collection methods and dates
• Known gaps or limitations in the data

✓ Fairness and Bias

• Performance metrics across different demographic groups
• Fairness definition and metrics used
• Known biases or performance disparities
• Mitigation approaches implemented

✓ Performance Limitations

• Accuracy ranges (not just best-case)
• Common failure modes and edge cases
• Environmental or contextual limitations
• Reliability over time considerations

✓ Uncertainty Information

• Explanation of confidence scores
• Guidance on interpreting probabilistic outputs
• Recommended decision thresholds for different risk levels
• Visualization of uncertainty when applicable

✓ Broader Impacts

• Environmental resource requirements
• Potential social and economic effects
• Accessibility considerations
• Long-term implications of system use

✓ Security and Privacy

• Vulnerability information (appropriate to audience)
• Data privacy practices
• Security testing conducted
• Incident response and responsible disclosure process

Exercises: Putting Ethics into Documentation Practice

Exercise 1: Ethical Model Card Creation

The mission: Create a model card for an AI system that balances honesty about limitations with clear communication of benefits.

Your task:

1. Choose a real or hypothetical AI system (e.g., a credit scoring algorithm, a medical diagnosis tool)
2. Create a 1-2 page model card following Google’s framework
3. Include at least three specific ethical considerations
4. Write limitations in clear, non-defensive language
5. Have a colleague review it and identify any missing ethical considerations

Reflection questions:

• Was it difficult to be honest about limitations while still presenting the system positively?
• Did you find yourself wanting to use vague language for sensitive issues?
• How did your perspective change when imagining different stakeholders reading the card?

Exercise 2: Ethical Red-Teaming

The mission: Practice identifying ethical documentation gaps that could lead to harm.

Your task:

1. Find documentation for an existing AI product or service
2. Play the role of an “ethical red team” trying to identify potential harms
3. Note at least three ethical considerations that are inadequately addressed
4. Rewrite these sections to better prevent potential harms
5. Consider how the revised documentation might affect user behavior

Reflection questions:

• Was important ethical information missing or just buried in technical language?
• Would a typical user understand the ethical implications from the documentation?
• How might business pressures have influenced what was (or wasn’t) disclosed?

Exercise 3: Multi-Audience Documentation Plan

The mission: Create documentation strategies for different stakeholders affected by an AI system.

Your task:

1. Choose an AI system with diverse stakeholders (e.g., a hiring algorithm affects candidates, HR, and management)
2. Identify 3-4 key stakeholder groups
3. For each group, outline:
   • Key ethical information they need
   • Appropriate format and detail level
   • How to make the information accessible and actionable
4. Create a sample one-page ethical summary for each stakeholder group

Reflection questions:

• How did the critical ethical information differ across stakeholder groups?
• Was it challenging to make technical ethical concepts accessible to non-technical audiences?
• Did you identify ethical considerations that wouldn’t be captured in typical technical documentation?

Resources: Your Ethical Documentation Library

Frameworks and Templates

• Model Cards for Model Reporting - Google Research paper with practical examples
• Datasheets for Datasets - The original paper with template questions
• AI Ethics Guidelines Global Inventory - Comprehensive collection of ethical frameworks

Organizations and Research

• Partnership on AI - Industry consortium resources on responsible AI
• AI Now Institute - Academic research on social implications of AI
• IEEE Ethics in Action - Technical standards body’s ethics resources

Essential Reading

• Weapons of Math Destruction by Cathy O’Neil - Classic examination of algorithmic harm
• Race After Technology by Ruha Benjamin - Crucial insights on algorithmic discrimination
• Ethics of AI and Robotics - Stanford Encyclopedia of Philosophy’s thorough overview

Test Your Knowledge

Take this quiz to test your understanding of ethical documentation principles and practices!

The Journey Continues: Your Documentation as Ethical Practice

Documentation isn’t just something you create once and forget. It’s an ongoing ethical practice that evolves with your system and the world around it.

In our next module, we’ll explore how to maintain and version your documentation as your AI systems change, ensuring that your ethical commitments remain current and effective throughout the system lifecycle.

Remember: The words you write today shape how AI systems will be used tomorrow. Make them count.

“The true measure of a technology isn’t what it can do, but what it helps humans do ethically.” — Document accordingly.