nextcloud / nextcloud/documentation
(Revamp proposal) Uploading big files > 512MB clarifications
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 628
- Forks
- 2.5k
- Avg merge
- 2d 11h
- Merged PRs (30d)
- 135
Description
The documentation here pulls together a lot of highly relevant tidbits of information, but it's also misleading to many readers (and overwhelming IMO).
I think this largely comes down to it not being immediately clear:
- who it is for (i.e. the 512MB limit isn't really a "limit" at all for those that use any of the official clients or the web interface which all support chunking, but could be for others connecting using non-NC specific WebDAV clients)
- where to start
- which of the tidbits inside are applicable to the readers situation or specific interests
- which parameters are merely about performance (throughput) and which are about actually being able to upload large files at all
I propose some refinements:
- Establishing an introduction/overview that helps people get the "lay of the land" a little quicker so that they can (a) grasp which limits are relevant to them (b) where to start
- Separate hard limits under certain circumstances (e.g. PHP upload_max_filesize if not using official clients) from harder to nail down limiting parameters that can cause issues (such as PHP and web server timeouts)
- Separating performance related adjustments from functionality related ones (i.e. changing chunk size versus parameters that when wrong actually prevent uploads entirely)
- Possibly conveying adjustments somewhere by the "layer" in the stack where they take place
- Possibly integrating in some diagrams
- Dropping references to version specific changes in behavior that occurred in things like nginx >5 years ago and are now standard (e.g. references to nginx 1.7.11 though I'll want to confirm before assuming this is truly the case) [I understand the merit of mentioning the version to help out readers that have been around awhile so they know to make adjustments, but at a certain point dropping things like this creates clearer docs so that changes are also more readily noted by readers)
- tighter integration with relevant sections the General troubleshooting chapter - i.e. https://docs.nextcloud.com/server/latest/admin_manual/issues/general_troubleshooting.html#web-server-and-php-modules
- Some consideration to even moving some parts of this to the General troubleshooting chapter (and potentially an Uploading specific section of it)
- For ongoing upload related behaviors that have open Issues (in GH) it might be worthwhile to reference them under a "Known Issues" section or something
This is just a starting point for documenting some of the ideas that have been rolling around in my head and for potential discussion before (eventually) preparing some PRs.
These are clearly not going to happen all at once, but thinking about the bigger picture increases the chance that something clearer and even more helpful comes out of the work (for both new readers and revisiting readers alike).
Feel free to pop into the comments and/or give a 👍/ 👎 /etc.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the big file upload configuration page and compare it with the linked General troubleshooting section on web server and PHP modules. Map the existing guidance by audience, hard limits, performance settings, and stack layer, then confirm which version-specific details remain relevant. Done means a clearer, better-integrated documentation structure agreed through the open discussion.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- nginx, php
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 32/100