Mack Palomäki: AI-Driven Documentation Workflows for Plone & Volto

Part 1: Collaboration rules. I have a very large file with rules that I use for prompts. For example:

• Rule 1: documentation first. Look in the official docs.
• Rule 11: no false security. Never say "this will work" unless proven.
• Rule 10: success is functional. Claim a success ONLY when there is a fully functional, useful, tested result.
• Rule 8: Loop detection. If the AI is repeating the same pattern, stop.

Part 2: What makes a good documentation prompt?

• Context: what is this code/module/function?
• Constraints: what format/style/standards?
• Output format: docstrings? Markdown? API reference? And can you save intermediate output so you can check the reasoning afterwards?
• Verification: How to check accuracy?

Specify what kind of docs you want? "Generate API docs." "Add verbose comments." "Create an architecture overview." "Compare v1 and v2 of this API and write a migration guide."

There are some tasks an AI can confidently do. Others not. I am a newbie in Plone, and have totally relied on AI for this presentation. I have had about 4000 hours of experience in AI though. It took about 10 minutes to prepare. That it can do well.

I gave it a task: "Create an architecture overview document." This took about 20 minutes. It could then self-critique the result. Some parts it thought it had done fine. But it confessed that performance numbers were made up. It could not have done this kind of self-critique a few months ago.

A documentation workflow:

• Developer writes code and creates prompt.
• AI generates initial docs.
• Developer reviews
• Dev adds missing content.
• AI validates technical claims.

You can create (or find) prompt templates for different doc types.

To reduce hallucinations:

• Require AI to cite sources, actual lines numbers, function names.
• Ask AI to state uncertainties explicitly. It is good to be very verbose about this, be really challenging.

Key takeaways:

• AI generates structure quickly, and then humans add context.
• Follow collaboration rules to avoid loops.
• Good prompts lead to good documentation.
• Documentation as code: part of the PR process.

Closing remark:

There are different AIs out there. I am using every single one of them. They all have different personalities. It is actually addictive in the way that gaming is. You have immediate feedback, visible progress, creative problem solving, that flow state where you lose track of time. That is powerful, because it means developers will actually want to document instead of avoiding it. Just... set a timer, because you can iterate forever!

In your prompt, always start with the collaboration rules.