MINOR: update docs for KIP-663, KIP-696, and KIP-671 (#9969)

Co-authored-by: Bruno Cadonna <bruno@confluent.io>

Reviewers: Jim Galasyn <jim.galasyn@confluent.io>, Matthias J. Sax <matthias@confluent.io>, Guozhang Wang <guozhang@confluent.io>, Bruno Cadonna <bruno@confluent.io>

docs/streams/architecture.html

@@ -110,6 +110,11 @@
         and Kafka Streams takes care of distributing partitions amongst tasks that run in the application instances. You can start as many threads of the application
         as there are input Kafka topic partitions so that, across all running instances of an application, every thread (or rather, the tasks it runs) has at least one input partition to process.
     </p>
+    <p>
+        As of Kafka 2.8 you can scale stream threads much in the same way you can scale your Kafka Stream clients.
+        Simply add or remove stream threads and Kafka Streams will take care of redistributing the partitions.
+        You may also add threads to replace stream threads that have died removing the need to restart clients to recover the number of thread running.
+    </p>
     <br>
 
     <h3 class="anchor-heading"><a id="streams_architecture_state" class="anchor-link"></a><a href="#streams_architecture_state">Local State Stores</a></h3>

docs/streams/upgrade-guide.html

@@ -91,6 +91,29 @@
         We extended <code>StreamJoined</code> to include the options <code>withLoggingEnabled()</code> and <code>withLoggingDisabled()</code> in
         <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-689%3A+Extend+%60StreamJoined%60+to+allow+more+store+configs">KIP-689</a>.
     </p>
+    <p>
+        We added two new methods to <code>KafkaStreams</code>, namely <code>KafkaStreams#addStreamThread()</code> and <code>KafkaStreams#removeStreamThread()</code> in
+        <a href="https://cwiki.apache.org/confluence/x/FDd4CQ">KIP-663</a>.
+        These methods have enabled adding and removing StreamThreads to a running KafkaStreams client.
+   </p>
+    <p>
+        We deprecated <code>KafkaStreams#setUncaughtExceptionHandler(final Thread.UncaughtExceptionHandler uncaughtExceptionHandler)</code>
+        in favor of <code>KafkaStreams#setUncaughtExceptionHandler(final StreamsUncaughtExceptionHandler streamsUncaughtExceptionHandler)</code>
+        in <a href="https://cwiki.apache.org/confluence/x/lkN4CQ">KIP-671</a>.
+        The default handler will close the Kafka Streams client and the client will transit to state ERROR.
+        If you implement a custom handler, the new interface allows you to return a <code>StreamThreadExceptionResponse</code>,
+        which will determine how the application will respond to a stream thread failure.
+    </p>
+    <p>
+        Changes in <a href="https://cwiki.apache.org/confluence/x/FDd4CQ">KIP-663</a> necessitated the KafkaStreams client
+        state machine to update, which was done in <a href="https://cwiki.apache.org/confluence/x/lCvZCQ">KIP-696</a>.
+        The ERROR state is now terminal with PENDING_ERROR being a transitional state where the resources are closing.
+        The ERROR state indicates that there is something wrong and the Kafka Streams client should not be blindly
+        restarted without classifying the error that caused the thread to fail.
+        If the error is of a type that you would like to retry, you should have the
+        <code>StreamsUncaughtExceptionHandler</code> return <code>REPLACE_THREAD</code>.
+        When all stream threads are dead there is no automatic transition to ERROR as a new stream thread can be added.
+    </p>
 
     <h3><a id="streams_api_changes_270" href="#streams_api_changes_270">Streams API changes in 2.7.0</a></h3>
     <p>