Apply feedback

Author: sfodagain

README.md

@@ -2,13 +2,17 @@
 
 [![Version](https://img.shields.io/pypi/v/awsiotsdk.svg?style=flat)](https://pypi.org/project/awsiotsdk/)
 
-The AWS IoT Device SDK for Python v2 connects your Python applications and devices to AWS IoT. Built on the AWS Common Runtime, it handles the complexities of secure communication, authentication, and device management so you can focus on your IoT solution. The SDK makes it easy to use AWS IoT services like Device Shadows, Jobs, and Fleet Provisioning.
+The AWS IoT Device SDK for Python v2 connects your Python applications and devices to AWS IoT. It handles the complexities of secure communication, authentication, and device management so you can focus on your IoT solution. The SDK makes it easy to use AWS IoT services like Device Shadows, Jobs, and Fleet Provisioning.
 
 **Supported Platforms**: Linux, Windows, macOS
 
+> **Note**: The SDK is known to work on older platform versions, but we only guarantee compatibility for the platforms listed above.
+
 *__Topics:__*
 * [Features](#features)
-* [Using SDK](#using-sdk)
+* [Installation](#installation)
+  * [Minimum Requirements](#minimum-requirements)
+  * [Installing from PyPI](#installing-from-pypi)
 * [Getting Started](#getting-started)
 * [Samples](samples)
 * [MQTT5 User Guide](./documents/MQTT5_Userguide.md)
@@ -30,7 +34,7 @@ The primary purpose of the AWS IoT Device SDK for Python v2 is to simplify the p
 * The [AWS IoT Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) allows to define a set of remote operations that can be sent to and run on one or more devices connected to AWS IoT.
 * The [AWS IoT fleet provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html) can generate and securely deliver device certificates and private keys to IoT devices when they connect to AWS IoT for the first time.
 
-## Using SDK
+## Installation
 
 The recommended way to use the AWS IoT Device SDK for Python v2 in your project is to install it from PyPI.
 
@@ -58,31 +62,15 @@ python -m pip install awsiotsdk
 
 ### Building from source
 
-```bash
-# 1. Create a workspace directory to hold all the SDK files
-mkdir sdk-workspace
-cd sdk-workspace
-
-# 2. Clone the repository. You could select the version of the SDK you desire to use.
-git clone -b <SDK_VERSION> https://github.com/aws/aws-iot-device-sdk-python-v2.git
-
-# 3. (Optional) Setup the version number of your local build. The default version
-#    for awsiotsdk is set to "1.0.0-dev", you can set the version number of the
-#    local build in "aws-iot-device-sdk-python-v2/awsiot/__init__.py"
-sed -i "s/__version__ = '1.0.0-dev'/__version__ = '<SDK_VERSION>'/" \
-  aws-iot-device-sdk-python-v2/awsiot/__init__.py
-
-# 4. Install using Pip (use 'python' instead of 'python3' on Windows)
-python3 -m pip install ./aws-iot-device-sdk-python-v2
-```
+See the [Development Guide](./documents/DEVELOPING.md) for detailed instructions on building from source and using local builds.
 
 ## Getting Started
 
 To get started with the AWS IoT Device SDK for Python v2:
 
-1. **Install the SDK** - See the [Using SDK](#using-sdk) section for installation details
+1. **Install the SDK** - See the [Installation](#installation) section for installation details
 
-2. **Choose your connection method** - The SDK supports multiple authentication methods including X.509 certificates, AWS credentials, and custom authentication
+2. **Choose your connection method** - The SDK supports multiple authentication methods including X.509 certificates, AWS credentials, and custom authentication. [MQTT5 User Guide connection section](./documents/MQTT5_Userguide.md#how-to-create-an-mqtt5-client-based-on-desired-connection-method) and [MQTT5 X509 sample](./samples/mqtt/mqtt5_x509.md) provide more guidance
 
 3. **Follow a complete example** - Check out the [samples](samples) directory for working code examples that demonstrate:
    - Basic MQTT connection and messaging
@@ -115,6 +103,9 @@ If you have a support plan with [AWS Support](https://aws.amazon.com/premiumsupp
 
 #### Mac-Only TLS Behavior
 
+> [!NOTE]
+> This SDK does not support TLS 1.3 on macOS. Support for TLS 1.3 on macOS is planned for a future release.
+
 Please note that on Mac, once a private key is used with a certificate, that certificate-key pair is imported into the Mac Keychain.  All subsequent uses of that certificate will use the stored private key and ignore anything passed in programmatically.  Beginning in v1.7.3, when a stored private key from the Keychain is used, the following will be logged at the "info" log level:
 
 ```

documents/DEVELOPING.md

@@ -0,0 +1,23 @@
+# Development Guide
+
+This document provides instructions for building the AWS IoT Device SDK for Python v2.
+
+## Building from source
+
+```bash
+# 1. Create a workspace directory to hold all the SDK files
+mkdir sdk-workspace
+cd sdk-workspace
+
+# 2. Clone the repository. You could select the version of the SDK you desire to use.
+git clone -b <SDK_VERSION> https://github.com/aws/aws-iot-device-sdk-python-v2.git
+
+# 3. (Optional) Setup the version number of your local build. The default version
+#    for awsiotsdk is set to "1.0.0-dev", you can set the version number of the
+#    local build in "aws-iot-device-sdk-python-v2/awsiot/__init__.py"
+sed -i "s/__version__ = '1.0.0-dev'/__version__ = '<SDK_VERSION>'/" \
+  aws-iot-device-sdk-python-v2/awsiot/__init__.py
+
+# 4. Install using Pip (use 'python' instead of 'python3' on Windows)
+python3 -m pip install ./aws-iot-device-sdk-python-v2
+```