Wanted to share a relevant short by Matt Pocock: https://www.youtube.com/shorts/Fj8DKMbdIzU ## TLDR: He talks about the tradeoff between asking an agent to understand a system through docs vs code. He doesn't like the idea of using docs as the source of truth, but as higher level knowledge base (e.g. glossary, architectural decision) and helping agents navigate the codebase. ## Discussion Question: What information have you found is better represented in the code vs in docs? ## Key Points: 1. Code should b be self explanatory for an AI agent to understand directly. 2. Docs are not executable and testable. 3. Docs can drift out of sync and no longer match code, causing conflicting sources of truth. 4. Docs should hold higher level context such as discussions and cross functional decisions (e.g. design and architectural decisions) 5. Use a thin layer of docs to help navigate the codebase ( insert ICM here) 6. Docs as the source of truth where reading them to understand the code is not ideal ## Relevance to my work: I am trying to understand how to implement ICM for ongoing app management and improvement (read as software factory). This tradeoff between holding truth in code vs docs is top of mind. For example, I'm currently doing a significant amount of UI work. In ICM, i have defined relevant user workflows and linked them to their relevant components. The workflow documentation provides higher level context and intent. However, I am still trying to determine how much documentation is enough. I want to keep reasoning behind decisions so future work respects them, without creating a second representation of the app. Some simple examples where the rationale is not always obvious from implementation: - We display a timestamp here because that level of granularity is important for this workflow. - We use green rather than blue here to distinguish completion vs continuation action. - We place this data together on the same row to reinforce their connection.

A question for those using ICM to provide software or consulting services: When you work with multiple customers, does one ICM system support all of them, with separate customer configurations, requirements, data, and outputs? Or do you create and maintain a separate ICM structure for each customer or software product? I’ve been thinking about this through the way I create my own products. I reuse many of the same standards, checks, scripts, and production methods, but different product types may still need different schemas and workflows. A devotional is not built exactly like a prayer card set, even though they share part of the same underlying system. I’m curious whether software providers (or consultants) approach this similarly. Do you maintain a common core and adapt it for each customer, keep every customer implementation completely separate, or use some combination of the two? I’m still learning how others structure this, so I would genuinely appreciate hearing what has worked for you—and where separation becomes important.