[docs-scanner] Contradictory guidance on --pull and --no-cache flags

[github-actions]

File: content/manuals/build/building/best-practices.md

Issue

The documentation provides contradictory information about when to use --pull versus --no-cache flags. In the "Use --pull to get fresh base images" section:

$ docker build --pull -t my-image:my-tag .

The --pull flag forces Docker to check for and download a newer
version of the base image, even if you have a version cached locally.

But then in "Use --no-cache for clean builds" section:

The --no-cache flag disables the build cache, forcing Docker to
rebuild all layers from scratch:

$ docker build --no-cache -t my-image:my-tag .

This gets the latest available versions of dependencies from package
managers like apt-get or npm. However, --no-cache doesn't pull a
fresh base image - it only prevents reusing cached layers.

The contradiction: The first section says --pull gets fresh base images. The second section says --no-cache gets latest dependencies but doesn't pull fresh base images. Then it recommends combining both flags for "completely fresh build."

Why this matters

A reader trying to understand which flag to use for getting updated dependencies would be confused. The document first suggests --pull is sufficient for getting fresh base images, then later says you need both --pull and --no-cache together. The relationship between these flags and what each accomplishes isn't clearly explained, leading to uncertainty about which flag(s) to use in different scenarios.

Suggested fix

Clarify the distinct purposes of each flag upfront:

• --pull: Forces checking for and downloading newer base image versions (affects the FROM instruction)
• --no-cache: Prevents reusing any cached layers, forcing all RUN commands to execute fresh (affects dependency installation)
• Combined: Gets both fresh base images AND fresh dependencies

Consider restructuring to present these as complementary rather than alternative solutions, with clear guidance on when to use each.

---

Found by nightly documentation quality scanner