File: content/manuals/compose/how-tos/multiple-compose-files/merge.md
Issue
The "Limitations" section at the end of the page is confusing and doesn't clearly explain what the actual limitation is:
Docker Compose supports relative paths for the many resources to be included in the application model: build context for service images, location of file defining environment variables, path to a local directory used in a bind-mounted volume.
With such a constraint, code organization in a monorepo can become hard as a natural choice would be to have dedicated folders per team or component, but then the Compose files relative paths become irrelevant.
Why this matters
A reader reaching this section would be confused because:
- The section starts by saying "Docker Compose supports relative paths" which sounds like a feature, not a limitation
- It's unclear what "such a constraint" refers to - is it the support for relative paths, or something else?
- The phrase "Compose files relative paths become irrelevant" doesn't explain what actually breaks or what problem the user will encounter
- There's no clear explanation of what happens in a monorepo scenario or why it's problematic
A reader trying to understand the limitations of merging Compose files would finish this section without understanding what they should avoid or what problems they might encounter.
Suggested fix
Rewrite this section to clearly state:
- What the actual limitation is (e.g., "When merging Compose files, all relative paths must be resolved relative to the base Compose file")
- What specific problem this causes in monorepo scenarios (e.g., "In a monorepo with team-specific directories, this means...")
- What happens when users encounter this limitation (error messages, unexpected behavior, etc.)
- How users can work around it (if applicable)
Alternatively, if this limitation has been resolved by the include feature mentioned earlier in the documentation, this section should either be removed or updated to note that include solves this problem.
Found by nightly documentation quality scanner
File:
content/manuals/compose/how-tos/multiple-compose-files/merge.mdIssue
The "Limitations" section at the end of the page is confusing and doesn't clearly explain what the actual limitation is:
Why this matters
A reader reaching this section would be confused because:
A reader trying to understand the limitations of merging Compose files would finish this section without understanding what they should avoid or what problems they might encounter.
Suggested fix
Rewrite this section to clearly state:
Alternatively, if this limitation has been resolved by the
includefeature mentioned earlier in the documentation, this section should either be removed or updated to note thatincludesolves this problem.Found by nightly documentation quality scanner