chunk size advice

1 files changed, 10 insertions, 3 deletions

diff --git a/doc/chunking.mdwn b/doc/chunking.mdwn
index d1dce317c..87408f8e1 100644
--- a/doc/chunking.mdwn
+++ b/doc/chunking.mdwn
@@ -9,15 +9,22 @@ Chunking also allows for resuming interrupted downloads and uploads.
 Note that git-annex has to buffer chunks in memory before they are sent to
 a remote. So, using a large chunk size will make it use more memory.
 
-To enable chunking, pass a `chunk=XXmb` parameter to `git annex
-initremote`.
+To enable chunking, pass a `chunk=nnMiB` parameter to `git annex
+initremote, specifying the chunk size. 
+
+Good chunk sizes will depend on the remote, but a good starting place
+is probably `1MiB`. Very large chunks are problimatic, both because
+git-annex needs to buffer one chunk in memory when uploading, and because
+a larger chunk will make resuming interrupted transfers less efficient.
+On the other hand, when a file is split into a great many chunks,
+there can be increased overhead of making many requests to the remote.
 
 To disable chunking of a remote that was using chunking,
 pass `chunk=0` to `git annex enableremote`. Any content already stored on
 the remote using chunks will continue to be accessed via chunks, this
 just prevents using chunks when storing new content.
 
-To change the chunk size, pass a `chunk=XXmb` parameter to
+To change the chunk size, pass a `chunk=nnMiB` parameter to
 `git annex enableremote`. This only affects the chunk sized used when
 storing new content.