[planede]

> For the record: to mount a multiple device btrfs filesystem, use an ordinary mount command with any one of the block devices that are part of the file system. Every device contains information about what other devices are supposed to be part of that filesystem.

If something works "automagically" like this then I jump into thinking about failure modes. Will it mount if one of the other devices are missing or failing? Will it just warn that the raid is degraded and I should add a new device? Will it mount read-only?

> I'm not sure if there are any techniques documentation writers can use to avoid this "hiding in plain sight" kind of problem.

The problem is probably lack of emphasis. It's guess it's hard to achieve in writing, if a solution is simple than you don't need many words to explain it, then it becomes easy to skip over.

[wtallis]

> If something works "automagically" like this then I jump into thinking about failure modes. Will it mount if one of the other devices are missing or failing? Will it just warn that the raid is degraded and I should add a new device? Will it mount read-only?

That's all well-documented, but it can also be summarized by saying that btrfs does the right thing. It won't mount normally if it's missing any devices, because running in degraded mode shouldn't be a silent error (especially at mount time).