[docs-scanner] OCI and Docker exporters: unclear dest and tar parameter behavior
Nobody has claimed this yet.
- 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
tarparameter
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:
-
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.") -
For
tar: What happens when set tofalse(e.g., "Whentrue(default), bundles output into a tar archive. Whenfalse, outputs the image layout as a directory structure.") -
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
destandtarparameters.
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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