Using AI to write docs
-
In the network UI, there is a setting called "VPN protection". First enable the feature and select how to route the client traffic.
This is a great feature. I hope it can be documented more thoroughly, to better understand how to benefit from it in all use cases and scenarios.
-
If you don't know what to write you can also not use AI. AI has a tendency to hallucinate and to blow up the text. If one accepts these downsides and the benefit of writing text faster is outweighing it, it may be a tool of choice.
Alternatively you can also integrate more deeply in your workflow...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.
-
If you don't know what to write you can also not use AI. AI has a tendency to hallucinate and to blow up the text. If one accepts these downsides and the benefit of writing text faster is outweighing it, it may be a tool of choice.
Alternatively you can also integrate more deeply in your workflow...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.
@nottheend In my experience, if AI has access to the source code, it can easily write tests to verify it's own accuracy which greatly reduces the hallucinations. And combined with a frontier model like Astra or Fable (overkill for documentation but just saying...) the accuracy is likely very high.
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.
-
I made a separate topic out of this @loudlemur to not mix with the release thread.
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.
-
@LoudLemur Thanks for this interesting question. It could be ok to draft docs by hand, then refine and polish with AI...
AI is too much verbose, as @girish noted....
-
I think AI for documentation is a strong way forward and I hope Cloudron experiments with it. A clear template works wonders for having the AI conform to a standard style of presentation. The burden falls on creating/finding an exemplary model which the AI can follow, and then providing a couple of iterations to tweak it with some human feedback.
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.
-
-
Here is our AIo repo:
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.
-
I'm mostly with @nottheend, @girish and others, although I do see some role, PROVIDING the model is given a really tight brief (prompt) on format, style etc.
Almost every instruction I give to AI includes "be very concise". -
Here is our AIo repo:
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.
@LoudLemur very interesting - will explore later.
Just brief relevant comment :
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.
-
I made a separate topic out of this @loudlemur to not mix with the release thread.
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.
Hello! It looks like you're interested in this conversation, but you don't have an account yet.
Getting fed up of having to scroll through the same posts each visit? When you register for an account, you'll always come back to exactly where you were before, and choose to be notified of new replies (either via email, or push notification). You'll also be able to save bookmarks and upvote posts to show your appreciation to other community members.
With your input, this post could be even better 💗
Register Login