undefined

points

[-]

We've found Opus/Gpt are really bad at technical writing. We've found ways around this by having guidelines like https://www.openalmanac.org/ai-patterns-to-avoid.md, which have worked quite well for us.

Understanding what is relevant to be documented vs not is definitely tricky and something we've spent a lot of time on. We found being more prescriptive about what should be documented is helpful, we incorporated guidance from diataxis for it (https://diataxis.fr/)

Also the wiki is primarily for your agents and not for people. Although we're working to improve the prose quality and structure so it is well written for humans too.

by ajrouvoet4 hours ago|

parent|

[-]

Do you mean that specifically those models perform badly without guidance or do all models need specific instructions for technical writing?

We have observed that it is a loss for teamwork that the sparring with AI is entirely lost when only the technical conclusion is recorded. I write to recover that for my team and an AI can use it to its advantage as a side effect.

It would be cool to have good tool support for this process, but I’d bet on support, not delegation in that case.

by reveriedev3 hours ago|

parent|

[-]

The models perform badly without guidance but we've found the guidance doesn't need a human in the loop (at least for this task). You can distill what makes a good wiki, what information should go in etc. and the models are good enough to do it reliably. That's what took the most time (researching and studying existing wikis)

When you say support do you mean something where you can collaborate with the model to maintain the wiki?

by ajrouvoet2 hours ago|

parent|

[-]

Yes: the human provides the qualitative judgement and the agent provides the executive function.