Why? The previous example should work.

It used wrong variable in second param,

file = IO::Memory.new "file contents"
# it be file not io
builder.file("upload", io, FileMetadata.new(filename: "test.txt"))

I'd prefer it if you simply fixed the variable name, instead of changing the example. Using IO::Memory is easier to understand here, I think. I am biased because I wrote that example though.

In my option, the plain text/binary file often to be use in most of usage, suck like archive file, image file etc. No one will use a IO::Memory.

It's an example. IO::Memory will be rare in practice but using a file makes the example not be self-contained.

We shouldn't suggest to use the block-less variant of File.open where we can avoid it.

Updated.