what is the deal with separating concept and task in documentation?Solved

It’s definitely not an arbitrary rule, @desmond. It actually comes down to user intent.

A Concept topic answers what something is and why the user should care. A Task topic answers exactly how to do it. When you blend them together, which LLMs naturally love to do because they just predict the next logical sentence, you create a cognitive nightmare for the reader.

Think about a developer just trying to get their local environment running before a standup meeting. If you bury step three under two dense paragraphs explaining the theoretical architecture of the API, they are going to lose their place, skip a step, and break something.

Here is a quick example of what your LLM probably did versus what your lead wants:

• Mixed (The Nightmare): 
  To initialize the database, which utilizes a sharded architecture to balance query loads across multiple nodes, open your terminal and run db-init –shard. Sharding is critical here because it ensures high availability. Once that finishes, you need to configure the port by…
• Separated (The Right Way):  
  • Concept:How Database Sharding Works (Put all your architectural theory, why we use sharding, and how the nodes communicate here. No actionable steps.)
  • Task: Initialize the Database 
    1. Open your terminal.
    2. Run the command: db-init –shard
    3. Verify the output says “Success”.

Tasks should be pure, actionable steps. Concepts should be pure, descriptive context. They need clear, distinct sections so the user can skim exactly what they need based on their current goal.

@pepijn is spot on about the human element but let me explain why your tech lead is enforcing this specifically in the age of LLMs. 

You might think your AI-generated hybrid document is helpful, but you are actually messing with our internal knowledge base. Modern AI search tools and Retrieval-Augmented Generation (RAG) systems rely on clean, structured data chunks. 

If a user asks our internal chatbot, “How do I configure the API?”, the system needs to fetch a pure Task chunk to give a clean, step-by-step answer. If the user asks, “What does the new API do?”, the system needs to fetch a pure Concept chunk. 

If your documentation mashes the what and the how into a single giant blob, the retrieval system gets confused. It grabs the whole blob and either hallucinates steps or vomits three paragraphs of theory when the user just wanted a terminal command. Separating concepts and tasks isn’t legacy formatting; it is literally the only way to make your documentation machine-readable for the AI tools we are trying to use!