Documentation as Intent, Not Reality

Documentation often serves as a high-level guide to how a library or SDK is intended to function, but it frequently fails to capture the nuance of implementation. As demonstrated by the author's experience with boto3 and its S3 transfer manager, documentation can be technically accurate regarding the existence of a parameter while remaining silent on how that parameter interacts with deeper, undocumented configuration layers. Relying solely on documentation creates a blind spot where developers assume a feature will behave as described, even when the underlying code has hardcoded ceilings or logic that overrides user-defined settings.

The Efficiency of Reading the Source

While reading documentation is faster, reading source code is more reliable for debugging complex production issues. When a system fails to behave as expected—such as an SDK failing to retry operations despite explicit configuration—the source code provides the only definitive explanation. By bypassing the abstraction layer of the documentation, developers can:

• Identify hidden constraints: Discover hardcoded limits or logic paths that are not exposed in the public API or documentation.
• Trace configuration resolution: Understand how parameters are passed through various layers of an application before reaching the execution logic.
• Eliminate guesswork: Stop relying on trial-and-error deployments or logging to infer behavior, and instead observe the exact conditions that trigger specific outcomes.

Ultimately, the author advocates for a shift in mindset: treat documentation as a starting point for understanding a tool's purpose, but treat the source code as the final authority on its actual behavior.