Documenting AI Development

Key Takeaways:

• Good documentation has various benefits, such as easier collaboration with stakeholders involved in AI development, smoother onboarding of new team members, increased trust & transparency and regulatory compliance readiness.
• Core elements of any documentation are code, quantitative information (such as performance metrics), and qualitative information (such as development decisions).
• The degree to which these elements are described in the documentation depends on its purpose and use, which looks different if the documentation is used for audits, project hand-overs or internal team reporting.
• A holistic documentation includes a general summary and description of the system, as well as detailed description of data, model and the whole AI system. There are various guiding frameworks on data, model and system cards to get you started.
• The format, accessibility and consumption of time are common problems that hinder both the effective utilization and quality of documentation. It is crucial to standardize and automate as much as possible of the documentation process, without compromising on individual needs. Learn here how trail helps in you in doing so.

Why (good) documentation of AI projects is important

While you might rarely find a developer or engineer who enjoys writing documentation, it's a critical practice for any organization that develops and employs AI systems. Documentation acts as the foundation for high-quality AI systems and enables to trace back development decisions, efficient collaboration, understanding, smooth onboarding of new team members, and adherence to regulatory requirements. However, documentation of AI systems is often overlooked, inadequately done due to time constraints or perceived as a low-priority task. The absence of good documentation can lead to costly bottlenecks, e.g. efficiency losses due to redundant work and too many meetings, or in fines due to failing to prove compliance.

Well-maintained documentation - be it for technical, reporting, or compliance purposes -  offers several benefits:

Easier collaboration

Accessible documentation helps to foster a common understanding among developers, aiding in grasping the project’s objectives, used data, models, reasoning behind certain decisions, and code. It also helps relevant managing stakeholders to evaluate the outcomes of the AI project more effectively. This is particularly important due to the interdisciplinary nature of machine learning projects, which increases the need for alignment of all stakeholders. Scheduling and attending meetings both is difficult to do and slows down everyone involved. Capturing all decisions and development results in a structured way gives everyone the chance to get on the same page efficiently. This allows your team to get the most out of the time on a call and to use meetings solely for project alignment.

Smoother onboarding

New team members can ramp up more quickly when comprehensive documentation of the system’s development history is available. It is pivotal for them to understand why certain algorithms were chosen, any enhancements made, and the underlying hypotheses that influenced these changes and model results, for fast and efficient onboarding. Many ML teams struggle with long downtimes when onboarding new employees, as sole code comments are insufficient to trace back past development. A lack of documentation additionally poses a high risk of losing knowledge when employees leave the company.

Increased transparency and trust

Clear documentation provides insights into how a model was trained and how it's operating, which can increase the system's trustworthiness and credibility of its outputs. Writing down technical details also helps to structure your thoughts and understand your AI model or system during development. A clear overview increases the likelihood of achieving your project objectives and keeps the focus on the goal.

Regulatory compliance readiness

With increasing regulatory demands maintaining thorough technical documentation ensures compliance and serves as an essential element of risk management (e.g. the ISO42001 lays down that every of its requirements must be documented and regularly updated to ensure responsible use of AI and to demonstrate adequate risk management). Under the EU AI Act, for instance, organizations who put high-risk AI systems or foundation models on the EU market are required to keep detailed, up-to-date technical documentation and documentation on the quality management systems chosen to safeguard the AI development. This includes information on the system design, architecture, training methodologies and risk treatments, among others.

‍

How to document AI development

The documentation of AI development should include a few core elements: code, qualitative information and quantitative information. The extent of each part and additional elements depends on the context and purpose of the documentation. Therefore, the content of your documentation can significantly vary based on whether it is for internal stakeholders, external auditors, clients or end-users. Further, the purpose of the documentation—whether for auditing, regulatory compliance, team updates and reporting, or onboarding—should dictate its depth and detail.

This is how you document your development process effectively:

• Set up an AI project charter and abstract: This part briefly outlines what the AI system is designed to do, its intended and potential unintended uses, the responsible project stakeholder and the project’s targeted outcomes (incl. the key metrics you will evaluate them on). It also outlines the inputs the model requires and the rationale for these requirements.
• Document the used data, to include comprehensive information about why and how these datasets were used. Data cards are a useful method to provide structure and detailed descriptions.
  • Recommended reads: Datasheets, Data Nutrition Label, Data Cards Playbook, Dataset Cards
• Document the model and its outputs, including the training process, model tuning, and the rationale behind the model's creation and single development choices. In this article, we have outlined what you should describe in model cards. For the model results, consider the expected output the AI model produces given an input, how it differs from the actual output (and reasoning), performed tests, as well as key metrics such as accuracy, recall or F1 scores.
  • Recommended reads: Model Cards for Model Reporting, Model Cards from Google, Method Cards, Consumer Labels
• Document the system: It's crucial to document the overall system architecture, especially when the documentation is used for compliance and governance purposes. This part should include details about other tools and systems used, how updates are performed, any dependencies, how the AI system interacts with other systems and data flows within the system.
  • Recommended reads: System Cards from Meta, FactSheets, ABOUT ML (also available in a more accessible version here)

As writing documentation is quite time-consuming and can be painful to many developers, automating and standardizing this process as far as possible should be considered to free up valuable development time. Learn how trail automates your technical and compliance documentation at the bottom of the article.

‍

Indicators that you need to change your documentation process

Regularly revisiting and revising the documentation process is essential to keep your documents useful and relevant. There are some indicators that it's time to reevaluate your documentation process:

You spend a lot of time on writing

Review the time you require to write documentation. There are many developer teams that value high-quality documentation or who have to prepare it in different formats for different stakeholders, which then easily takes up 25-30% of the time spent on an AI project. If documentation consumes a disproportionate amount of development time, consider implementing automation tools to gain back time and standardize the process as much as possible. This was part of the reason why we have built an automated documentation tool: trail can generate high-quality documentation in a few minutes instead of hours - while still paying respect to both the requirements of your organization or of an underlying standardization framework. You can test it here for free.

Delayed projects

Technical documentation is often an essential part of the project deliverables and therefore cannot be ignored. But as teams are focussing on the fast-paced day-to-day development, trying to meet all the specifications of the AI model or system, documentation plays a secondary role. Most often, teams then draft or update the documentation in its final form at the very end of a project, at a point where initial development decisions are already forgotten. This leads to additional workload, delayed project delivery, and incomplete documentation. Regularly integrating documentation updates rather than postponing them to the project's end can prevent bottlenecks and ensure smoother project transitions.

No utilization of documentation

While some teams can deliver relevant documentation in time, many teams also state that this documentation is something nobody looks at afterward, making writing documentation a non-value-adding output and potentially a time waste. While this would be another reason to automate as much as possible of the documentation process, this should also be a concern to revisit the actual purpose of the documentation. Unstructured and inaccessible writing hinders the reader to understand your AI system or development process. Well-kept documentation can be a selling argument for your clients or a necessity for your colleagues if they want to reproduce your AI models. If the documentation is not being used as intended or fails to assist new team members and clients effectively, its format, accessibility, or comprehensiveness may need to be reassessed.

Failing to meet governance and compliance needs

Not only customers and colleagues want (and need) to understand what your AI system is capable of, how it works, why it works like it does and what outputs it produces. Also, your compliance teams and auditors require comprehensible but extensive documentation of the systems. The EU AI Act, for instance, requires organizations to maintain detailed documentation about the functioning of an AI system, incl. metrics and training data - elementary to properly assess any harms that could arise if the AI system fails or is misused. Effective documentation should also provide all necessary details for governance and compliance processes, to demonstrate trustworthiness and adequately manage risks.

Automating documentation

Documenting your AI systems and its development process is an essential element of structuring and distilling knowledge, aligning both internal and external stakeholders, as well as in fostering understanding about your system. Effective documentation should be comprehensible and accessible to the reader, while integrating all relevant information. It acts as the basis of your AI governance, enabling you to demonstrate trust and transparency, necessary to achieve compliance with AI policies and regulation.

If you are struggling to write accessible, useful and qualitative documentation on your AI system development, you should consider automating your documentation process with trail. The automated documentation by trail frees up time that you can use for value-adding development tasks and guides you through the requirements of various AI governance frameworks and standards, without compromising on your individual needs. We connect to your development environment in a few lines of code and generate automated and high-quality documentation of AI projects. Learn more about documenting with trail here.