Blog post written by @asanvaq and @sophie.pages.
We are proud to share that Canonical’s Open Documentation Academy (CODA) has now an AI guide! But why did we create one? And how did we craft one that addresses our contributors’ needs?
Context
As Technical Authors (TAs), we started seeing an increasing number of AI-assisted contributions. Some enhance the content, others create noise: AI-generated contributions filled with emojis, bots committing directly and generating comments impersonating humans, etc.
Inspired by @sally-makin’s AI policy for the Server docs, we decided to create a similar guide adapted to the particularities of CODA while keeping it concise and enforceable.
Our initial draft and ideas
We started by clarifying why an AI guide is important for the CODA community. While we don’t ask contributors to put AI tools aside, we want them to understand how using AI impacts their experience with CODA and how it affects what they can expect to learn.
The use of AI in that context is quite different from our other projects, where the objective is to contribute quickly and efficiently. We identified the three principles that should be followed by those who decide to use AI in CODA: honesty, learning, and responsibility. Contributors should critically review AI outputs and make changes accordingly. This is also a key part of the learning process we hope contributors are embarking on. To support contributors, we defined examples of appropriate as well as inappropriate AI use. Our guide states we will reject contributions where there has been inappropriate AI use.
Discussion with the CODA community
After several internal iterations on our AI guide, we brought it to one of our Community Hours so we could openly discuss with external contributors what we wanted our guide to be like. Those contributors had varied ideas and opinions about how AI should be used in CODA.
CODA’s stance on AI
Our discussion started with defining which stance CODA should take with respect to AI. We discussed whether this document should encourage the use of AI or not. Some also proposed to include recommended models, while others were against it.
Multiple members expressed that AI, especially for writing, is becoming the new norm, and it’s easy for contributors who don’t understand technical writing to rely on it too much. Some even discussed whether a ban on AI contributions could be enforced.
We agreed that the objective of this guide is to advise participants on how to make the best use of AI for the purpose of CODA. We decided to focus on the quality of the contribution and mitigate the harm irresponsible use of AI can do. Being overly specific with our guidelines could have a negative effect.
AI usage disclosure
Having participants clearly acknowledge AI use was strongly supported by members. We agreed that AI can be very useful for certain tasks, such as grammar checking for neurodivergent participants. By defining the use of AI as acceptable, participants will be more likely to disclose their AI use and critically assess whether its use is needed or not.
Learning opportunities when AI is involved
Members expressed their concern over the lack of learning when AI is used inappropriately. It is important for contributors to be self-aware of their level. If an issue is too advanced for them and they choose to complete it using AI, it is a missed learning opportunity. This is especially relevant for beginners. Even if there are some tasks that can easily be done with AI, it doesn’t mean that AI should be used.
It can be very challenging to identify AI usage, so we agreed on the need to provide mentors with guidance on how to assess this.
Finalization
We debated whether it would be useful to create separate guidelines for beginners, where AI is not encouraged, and for those with more experience, where learning how to use AI in documentation would be beneficial. We concluded this would overcomplicate the guide unnecessarily. We decided to create one guide that would apply to all contributors in CODA.
To simplify our guide, we decided to remove the examples of accepted use and only show what we would not accept. We also added guidance for our mentors on how to identify and address irresponsible use of AI in the new mentor’s handbook.
We condensed and clarified why the guide matters.
Concluding remarks
Our CODA AI guide reflects our stance on AI contributions as of right now. We will be adapting this guide as time goes on, based on our experience, the community’s input, and advances in the field. If you have any suggestions or remarks, please drop them in the comments.
We created an issue to improve this guide further. If you are interested, feel free to comment on it and we can assign it to you.
We run bi-weekly Community Hour sessions where we discuss many other documentation-related topics, so join our discussion there!