Ask HN: How is your team changing documentation for AI-assisted coding?

3 pointshubraumhugo23d ago1 comments

The thread on whether AI sessions should be part of the commit (https://news.ycombinator.com/item?id=47212355) got me thinking about documentation more broadly. How do you document when agents write most of the code?

Specs and intent docs (plan.md, Linear ticket, change records) seem to become more important since they're what agents work from. On the other hand, the traditional RFC/architecture docs drifts out of sync faster.

How are you adopting your documentation workflows internally? How do you get feedback on specs before implementation?

1 comments

jumpalongjim22d ago

I find that communicating with AIs is enhanced by using Mermaid diagrams, which the AIs love to write and can convey quite a lot of complexity in an easily consumable format. It's really helpful to have a nice diagram to study rather than a wall of text. (AIs really love you to give you a wall of text ;) )

Mermaid is useful because it's text that can be checked in and versioned as usual.

j / k navigate · click thread line to collapse

Ask HN: How is your team changing documentation for AI-assisted coding?

3 pointshubraumhugo23d ago1 comments

How are you adopting your documentation workflows internally? How do you get feedback on specs before implementation?

1 comments

jumpalongjim22d ago

Mermaid is useful because it's text that can be checked in and versioned as usual.

j / k navigate · click thread line to collapse