Thursday thought exercise for y'all - how do you handle "best practices" in docs, and how would you convert those to config for coding agents?
In my experience, requests for best practices docs tend to be "distill 30k pages worth of content into a one-pager" - which doesn't actually work. So we tend to pick some particular persona or job-to-be-done and provide best practices for that, which just restates content that is scattered across more detailed task-oriented or feature-oriented docs pages.
Orgs are now starting to look at "what Cursor Rules or Claude Hooks can I distribute for my product" - which looks an awful lot like "best practices" distilled into config. So my first question becomes - what persona or job-to-be-done are we trying to support through this config? One stack's rules/hooks may look very different from another stack's - or if you're looking at it from a persona perspective, a database administrator's rules/hooks are likely to be very different from a developer building a CRUD-based web app.
Has anyone seen any examples of orgs/products that are doing this well yet? Have you started having these convos in your org? How are y'all thinking around these things?