Update docs on termination message size to correctly reflect k8s info

Prior to this commit we documented the maximum termination message size in our developer
docs as 2048 bytes. This is incorrect - the maximum is 4096 according to the link included
in that doc.

This commit updates the number to 4096 and adds a bit more context for anyone browsing
that info. It also updates the docs/tasks.md file to more clearly explain that a large
termination message will trigger a failure of the TaskRun and to call out the guidance
on keeping results small.

docs/developers/README.md

@@ -277,7 +277,12 @@ Instead of hardcoding the path to the result file, the user can also use a varia
 ### Known issues
 
 - Task Results are returned to the TaskRun controller via the container's
-termination log. At time of writing this has a capped maximum size of ["2048 bytes or 80 lines, whichever is smaller"](https://kubernetes.io/docs/tasks/debug-application-cluster/determine-reason-pod-failure/#customizing-the-termination-message).
+termination message. At time of writing this has a capped maximum size of ["4096 bytes or 80 lines, whichever is smaller"](https://kubernetes.io/docs/tasks/debug-application-cluster/determine-reason-pod-failure/#customizing-the-termination-message).
+This maximum size should not be considered the limit of a result's size. Tekton uses
+the termination message to return other data to the controller as well. The general
+advice should be that results are for very small pieces of data. The exact size
+is going to be a product of the platform's settings and the amount of other
+data Tekton needs to return for TaskRun book-keeping.
 
 ## How task results can be used in pipeline's tasks
 

docs/tasks.md

@@ -470,8 +470,13 @@ small amounts of data, such as commit SHAs, branch names, ephemeral namespaces,
 
 If your `Task` writes a large number of small results, you can work around this limitation
 by writing each result from a separate `Step` so that each `Step` has its own termination message.
-About size limitation, there is validation for it, will raise exception: `Termination message is above max allowed size 4096, caused by large task result`. Since Tekton also uses the termination message for some internal information, so the real available size will less than 4096 bytes. For results larger than a kilobyte, use a [`Workspace`](#specifying-workspaces) to
-shuttle data between `Tasks` within a `Pipeline`.
+If a termination message is detected as being too large the TaskRun will be placed into a failed state
+with the following message: `Termination message is above max allowed size 4096, caused by large task
+result`. Since Tekton also uses the termination message for some internal information, so the real
+available size will less than 4096 bytes.
+
+As a general rule-of-thumb, if a result needs to be larger than a kilobyte, you should likely use a
+[`Workspace`](#specifying-workspaces) to store and pass it between `Tasks` within a `Pipeline`.
 
 ### Specifying `Volumes`