docker / docker/cli

docker man pages need some love

Open
#923 21 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

exp/beginner help wanted kind/docs
Dominant language
Go
Stars
6.1k
Forks
2.2k
Avg merge
1d 15h
Merged PRs (30d)
43

Description

Executive summary: there are a number of docker-* man pages available under man/, they all need some love.

Formatting

For one thing, formatting/typesetting needs to be cleaned up. The rules (from the top of my head) are:

  • literals (like option names, literal values like true or false, or examples) should be bold;
  • variable parts (like option values to be substituted) should be italic (note this is frequently rendered as underlined when viewing a man page in a terminal);
  • optional parts should be enclosed into square brackets;
  • in general, = between the --option and the value should be omitted;
  • angle brackets (like <value>) should not be used.

For more rules and examples, check man-pages(7).

For example, here's the correct formatting:

--memory-limit value[SUFFIX]

Sets the memory limit. SUFFIX is optional and can be one of b (bytes), k (kilobytes), m
(megabytes), or g (gigabytes).

Source:
**--memory-limit** *value*[*SUFFIX*]

Sets the memory limit. *SUFFIX* is optional and can be one of
**b** (bytes), **k** (kilobytes), **m** (megabytes), or **g** (gigabytes).

As an example of such work, please see https://github.com/docker/cli/pull/922

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 in the docker-* man pages under man/ and compare their formatting with the man-pages(7) style guide and the example in pull request 922. Update the pages so options, values, literals, optional parts, separators, and angle brackets follow the stated rules; done means the affected pages consistently match those conventions.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker
Domain
cli, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.