Add files documentation articles

[SariSaar]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
dev-docs	Ready	Preview, Comment	May 22, 2026 10:05am

[shareoc]

I haven’t followed ANY of the files related conversation so far, so I’m really coming from a blank slate here. I had trouble understanding how this feature works on a high level. I started from the Files in Sharetribe article, and it dives directly into advanced concepts. As a reader, who does not know much about this feature, I would benefit from an Introduction or an architectural overview of how this feature works and what it can be used for. See this comment: https://github.com/sharetribe/dev-docs/pull/76/changes#r3209064101

I really liked the file-lifecycle article and I think it's a great approach having step-by-step API level instructions. You were considering a how-to article, but I think having more examples how interaction with the API works like the uploading a file section, would be really beneficial!

Something to consider: would the Files article work better under References > Files?

I didn't dive too deep into the Files in Sharetribe article yet, so I could review that again at some point in the future

[SariSaar]

I haven’t followed ANY of the files related conversation so far, so I’m really coming from a blank slate here. I had trouble understanding how this feature works on a high level. I started from the Files in Sharetribe article, and it dives directly into advanced concepts. As a reader, who does not know much about this feature, I would benefit from an Introduction or an architectural overview of how this feature works and what it can be used for. See this comment: https://github.com/sharetribe/dev-docs/pull/76/changes#r3209064101

I really liked the file-lifecycle article and I think it's a great approach having step-by-step API level instructions. You were considering a how-to article, but I think having more examples how interaction with the API works like the uploading a file section, would be really beneficial!

Something to consider: would the Files article work better under References > Files?

I didn't dive too deep into the Files in Sharetribe article yet, so I could review that again at some point in the future

Excellent points! I'll review the beginning of the Files in Sharetribe article from this point of view – I notice I was wary about potentially having overlap with no-code Help center content, but I guess there's still a middle ground between the two extremes.

As for the Files reference, I believe that's coming from Core side, though I'll need to double check that still. I think that the reference article will go fairly deeper still into the technical details, so once that exists we can then aim the Files in Sharetribe article between Help center and reference in terms of technical vs explanatory.

[SariSaar]

I haven’t followed ANY of the files related conversation so far, so I’m really coming from a blank slate here. I had trouble understanding how this feature works on a high level. I started from the Files in Sharetribe article, and it dives directly into advanced concepts. As a reader, who does not know much about this feature, I would benefit from an Introduction or an architectural overview of how this feature works and what it can be used for. See this comment: https://github.com/sharetribe/dev-docs/pull/76/changes#r3209064101
I really liked the file-lifecycle article and I think it's a great approach having step-by-step API level instructions. You were considering a how-to article, but I think having more examples how interaction with the API works like the uploading a file section, would be really beneficial!
Something to consider: would the Files article work better under References > Files?
I didn't dive too deep into the Files in Sharetribe article yet, so I could review that again at some point in the future

Excellent points! I'll review the beginning of the Files in Sharetribe article from this point of view – I notice I was wary about potentially having overlap with no-code Help center content, but I guess there's still a middle ground between the two extremes.

As for the Files reference, I believe that's coming from Core side, though I'll need to double check that still. I think that the reference article will go fairly deeper still into the technical details, so once that exists we can then aim the Files in Sharetribe article between Help center and reference in terms of technical vs explanatory.

@lyyder and @walterrw maybe a question for you here as well. I can see in Shortcut that the documentation card for this feature includes API reference. Have you considered a Files reference article (similar to other articles in References) and what that might contain? If you have some ideas on what that might be (separate from the API ref), you can either write it directly or you can give me some pointers on what to include and I can create the first version for your review.

[shareoc]

LGTM! Mostly stylistic/grammatical comments.

One general comment: The concept of "Sharetribe storage" is a bit ambiguous. Based on the graph, it looks a different entity entirely from the API, is that correct? It's referred to as "Sharetribe storage", "File storage" and just "storage" – consistent naming could also help!