docker / docker/docs

[docs-scanner] OCI and Docker exporters: unclear dest and tar parameter behavior

Open Beginner friendly
#25,663 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area/build
Dominant language
Markdown
Stars
4.7k
Forks
8.5k
Avg merge
2d 18h
Merged PRs (30d)
108

Description

File: content/manuals/build/exporters/oci-docker.md

Issue

The dest and tar parameters are documented in the parameter table but their behavior is not adequately explained, leaving readers uncertain about how to use these exporters.

1. The dest parameter behavior when omitted is not documented:

The parameter table shows:

| Parameter | Type | Default | Description |
| dest | String | | Path |

The description "Path" doesn't explain what happens when dest is not specified. However, the overview page (_index.md) shows an example using type=docker without dest:

$ docker buildx build \
  --output type=docker,name=<registry>/<image> .

And states: "have that image loaded to the local image store". This behavior is not documented in oci-docker.md where readers would look for detailed parameter information.

2. The tar parameter behavior when set to false is not explained:

The parameter table shows:

| Parameter | Type | Default | Description |
| tar | true,false | true | Bundle the output into a tarball layout |

The description doesn't explain what happens when tar=false. Does it create an unbundled directory? Does it require dest to be specified? This is not documented.

Why this matters

A reader trying to use the oci or docker exporters would look at oci-docker.md for parameter documentation. They would see that dest is optional but wouldn't know:

  • Whether they need to specify it
  • What happens if they don't specify it
  • How it interacts with the tar parameter

The terse parameter descriptions ("Path", "Bundle the output into a tarball layout") don't provide enough information for readers to understand the different output modes available.

Suggested fix

In oci-docker.md, expand the parameter descriptions to explain:

  1. For dest: What happens when it's not specified (e.g., "Path to output file. If not specified and the builder supports it, the image is loaded to the builder's image store.")

  2. For tar: What happens when set to false (e.g., "When true (default), bundles output into a tar archive. When false, outputs the image layout as a directory structure.")

  3. Add a section (similar to the "Multi-platform builds" section in local-tar.md) that explains the different output modes with examples, or clarify the relationship between dest and tar parameters.

Alternatively, if dest is effectively required for these exporters to function, state this clearly in the description rather than leaving it blank.


Found by nightly documentation quality scanner

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with content/manuals/build/exporters/oci-docker.md, then compare the exporter example in _index.md and the related section in local-tar.md. Confirm the documented behavior for omitted dest, tar=false, and their interaction, then update the parameter descriptions or add examples. Done means readers can distinguish the available output modes and know when dest is needed.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.