Add files documentation articles#76
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
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
| for example that it does not have malware. In addition, the backend | ||
| verifies that the file mime type is acceptable and the size is less than | ||
| 1GB. | ||
|
|
There was a problem hiding this comment.
Should there be a separate section on limitations, e.g. what kind of files can be uploaded? Or is that handled in the API reference?
There was a problem hiding this comment.
The template doesn't have an explicit list of allowed files, and the check is made on the API level. I would imagine that the necessary details will be available in the API reference – if that's not the case, then we can for sure amend this part.
| const ownFileResource = await sdk.ownFiles.create({ ...metadata }).data; | ||
| ``` | ||
|
|
||
| This step also validates that the file mime type is supported. |
There was a problem hiding this comment.
What mime types are supported?
There was a problem hiding this comment.
Maybe pinging @lyyder and @walterrw on this – how closely do we want to document supported/blocked mime types? I did find the categorization in src/sharetribe/util/file_security.clj. I don't know what the security balance is in terms of documenting the categories externally, so any advice is welcome!
| The actual file is uploaded directly to storage with the URL and other | ||
| details from the response, and the upload does not use Sharetribe APIs. | ||
| The SDK has another helper function to upload the file. |
There was a problem hiding this comment.
This sounds interesting! Could this flow be elaborated in the Files in Sharetribe article? That is, explaining the interaction between the client, our APIs, and the file storage. I feel like once I made it to this sentence, I started understanding how the architecture of file uploads work
There was a problem hiding this comment.
Good highlight! I added some more explanation as well as a visual for explaining this. Let me know if this still requires more elaboration!
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. |
SariSaar
changed the title
SariSaar
force-pushed
the
files-documentation
branch
from
0627ecf to
8462fcd
Compare
2 participants
No description provided.