Read SPEC.md. It is short.

OK, sure, I will do that.
Wait, it's 5,414 words !!
And a lot of what it says is already said in the repo README.
So I end up scan-reading, scan-scrolling, looking for new information that I don't have already. Eventually give up, no appetitie to explore further, which is silly, because there could be some gems.

I'm not picking a fight, I respect what you're doing and always interested in your explorations, but I think this is an almost perfect example of AI verbosity, repetition and lack of clarity, which earlier comments hinted at. If anything, I would say it proves why AI should NOT be used for documentation, at least not in this way, and why hand-crafting technical docs is the more reliable approach.

https://forgejo.wanderingmonster.dev/WanderingMonster/AIo

We spent a lot of time on considering how to document our projects taking into account AI.

It is easiest to try with a greenfield (new) coding project, but the AIo spec also shows how to introduce it to a brownfield (pre-existing) project, too.

We hope you like the cool artwork and might like to try using some of the procedures there. We have been working on this for half a year or so.

Readability was mentioned by @girish. We naturally assume human readability is meant here, and that is important. In the future, increasingly larger amounts of code will be created, debugged, documented and maintained by AI. (We think of this as being AI-Forward.) The distinction between documentation and code is becoming blurred, as AI coders are using the documentation as instructions. We should consider AI agents as part of the readership and perhaps consider them as 1st Class Citizens (!), when we create documentation.

We have been investigating this area and to keep discussion going, here are 6 suggestions for making documentation better suited for AI.

(SPOILER ALERT - Shield your eyes, this is AI generated!)

Six things that make docs genuinely useful to AI

• One document, one job. Tutorial, how-to, reference, or explanation — never mixed. A page that switches modes halfway retrieves badly and gets summarised wrong.

• Put the metadata at the top. Title, purpose, audience, status, and last-updated date in a header block. This is what lets a tool decide whether the page is relevant before reading it.

• Say the context out loud. Prerequisites, assumptions, and where this sits relative to everything else. A model has no hallway to ask in — anything "everyone knows" is invisible to it.

• Write in self-contained chunks. Descriptive headings, one idea per section, no "as mentioned above". Retrieval hands over fragments, not whole documents, so each fragment has to stand alone.

• Be exact and executable. Real file paths, real commands, real values — no placeholders, no "adjust as needed". Anything ambiguous gets guessed, and a confident wrong guess costs more than a gap.

• Don't restate what the source already says. Directory trees, function signatures, and config keys are read directly and go stale fast. Document the why — intent, constraints, dead ends — which is the part nothing else records.

The last one is usually the least intuitive to a room and the highest-leverage: most teams' docs are ~40% restated structure that the tool would rather read from the source anyway.

AI is too much verbose, as @girish noted....

I am with @nottheend, I use AI as a tool extensively, but I also find it needlessly verbose. It's not my style and I don't like docs which are wordy. In fact, I would rather sacrifice accuracy for readability (I know, this is maybe controversial for technical documentation). If the Cloudron docs don't follow this, it's only because I am not a technical writer like @d19dotca

For Cloudron docs, I prefer to handwrite them since it helps me doublecheck the features, the UI/text etc. I also write the blog, forum post and newsletter in parallel altogether. Writing helps me think clearly, and I can communicate and discuss any gaps in the features with the team.

I only say it because I do tend to do writing and documentation for technical products as a small part of my job, and ever since giving it access to product source code, the accuracy of its responses has been significantly better.

Agree though that AI isn't necessary, especially if the people writing the documentation are the ones developing the product in the first place (which is the case with Cloudron), because they'll know better than pretty much everyone what the intention is and how something is meant to work. AI can still be useful though, as it can help spot errors, find better ways to write things, ensure written consistency across all the documentation, etc.

Just my two cents.

But the question is very generic. AI can be seen as a tool in this context and I feel such fundamental discussions should happen somewhere else.