I've come to the same conclusion: don't say in markdown what you meant to say in code - spend the time to make the code more clear. The code is always the source of truth, and stale docs (they all get stale) are a constant drag on the LLMs pattern matching capabilities. If you want the LLM to follow certain patterns, you have to make your code base exemplify those patterns, not write about them.