Our Blog

How Better AI Documentation Practices foster Transparency in Organizations


As artificial intelligence systems become more integrated into daily life, the need for transparency in how those systems work and operate grows. A better understanding of the AI/ML  development, deployment, and decision-making processes can support user trust in AI/ML  systems. Users need assurance that these systems will reliably offer accurate and informed outputs, safeguard against failures, and protect and uphold privacy. Transparency involves making a system’s properties, purpose, and origins clear and explicit to users, practitioners, and other impacted stakeholders. It is a foundation for both internal accountability among the developers, deployers, and API users of an AI/ML  system and external accountability to customers, impacted non-users, civil society organizations, and policymakers. 

Governments and international government institutions are pressing for stronger transparency of AI systems to ensure safe and reliable use. The recently passed EU AI Act, the White House Executive Order on the Safe, Secure, and Trustworthy Development and Use of AI, and the Hiroshima Process International Code of Conduct for Advanced AI Systems are just some examples of emerging policy calls emphasizing the importance of transparency. However, these examples differ in their specific requirements and requests. Standardizing clear and rigorous approaches to the documentation of models, training data, and impacts on society would advance these shared goals of transparency and the societal accountability it enables. Standardization would also reduce unhelpful compliance burdens created by overlapping but different requirements for transparency issued from different jurisdictions and authorities. 

PAI’s ABOUT ML initiative aims to increase the standardization and improve the rigor of AI/ML documentation. “Documentation” includes two key components: “artifacts,” which provide details of AI/ML  systems, and “processes,” which describe the steps followed to create artifacts.  

ML Documentation in Practice 

PAI’s initial contribution to standardization was a detailed reference document of best practices in AI/ML  documentation, cited in the White House Blueprint for an AI Bill of Rights as an important effort to move from principles to practice.  After identifying that many organizations run into implementation challenges when attempting to institute or improve AI/ML documentation practices, PAI conducted pilots to test and improve the real-world usability of the ABOUT ML recommendations. Regardless of an organization’s size, specific domain, or product, the lessons learned in these pilots can help all organizations understand the challenges of implementing documentation best practices. 

The most recent ABOUT ML pilot was conducted in collaboration with Intuit, a large consumer-facing financial software and services company. PAI and members of the Intuit pilot explored how their responsible AI intake review processes could be further improved to streamline artifact and process creation. Pilots were also conducted with the United Nations Office for the Coordination of Humanitarian Affairs (UNOCHA) and Biologit, a start-up in the pharmacovigilance field

Emerging Themes

Over the course of the three pilots, we saw the following themes emerge in the pursuit of AI transparency and enabling better AI/ML documentation:

Theme 1: Identifying Common Challenges to Achieving Transparency Through Documentation Practices

Key Takeaway

Organizations should support a culture that values transparency by identifying and addressing documentation challenges and barriers. They should anticipate and plan for documentation challenges. Chances are that the primary challenge found across these three pilot teams –maintaining and updating documentation–, may not be unique to just the three pilot organizations but other organizations as well. Addressing these challenges will require providing the necessary resources to empower teams to prioritize and contribute to documentation practices; employee time and effort deserve particular attention here. Even though “financial cost” was the lowest ranked cost from an individual perspective, there are clear indirect financial costs for the organization as a whole associated with the time and effort required to support documentation practices—but the alternative of poor or absent documentation can create its own costs through inefficient internal coordination or external reputational costs.  

Theme 2:  Coordinating Internal Procedures to Develop Better Documentation Practices

Key Takeaway

For any organization looking to build out their internal best practices, it’s important to start by establishing internal procedures across all relevant teams within an organization. Such procedures may include:

  • Developing or instilling a shared understanding of the “why” or purpose of documentation for internal teams interacting with documentation artifacts and processes. 
  • Building better communication between internal teams responsible for creating documentation artifacts. 
  • Ensuring coordination between relevant teams in the artifact creation process (e.g., coordination between engineering, marketing, leadership, etc.) to allow for better visibility and involvement in current practices.
  • Making documentation artifacts more accessible across the organization, including access points and knowledge transfers of artifacts located within an organization and careful consideration of person-or-team-specific content that goes into the development of the artifacts. 

Coordination of internal practice can be helpful to achieve the desired quality and standard of these artifacts as well as building opportunities to engage teams in different modes of knowledge sharing. 

*Different artifacts may benefit from centralized or decentralized approaches in the creation process. 

Theme 3: Tailoring Documentation for the Needs of Different Stakeholders

Key Takeaway

Organizations that want to achieve clarity on what to document and who to document for should consider mapping out the user journey of various intended audiences. By focusing on the sentiments, incentives and motivations, and barriers for intended audiences, any team can determine a good starting point for specifying documentation goals. If possible, it is highly recommended that all stakeholders be actively involved in this exercise. It is important to note that this exercise is useful even if a given organization’s target audience cannot be involved, for example, if processes are proprietary knowledge. 

For any questions, concerns, or to learn more about the ABOUT ML work, please reach out to Albert Tanjaya (albert@partnershiponai.org)

To learn more about our work, sign up here.