Can we do better in the docs?

[hadley]

e.g. https://news.ycombinator.com/item?id=30765650

Maybe more documentation generation with code?

[yutannihilation]

It seems the link cannot be opened without a ycombinator account. What does it say?

[hadley]

Sorry, must’ve pasted the wrong link. Should work now

[yutannihilation]

Thanks, it works now.

[PierreENOlivier]

The main issue I have with the documentation is in knowing which options are available for each arguments and where to get information for each of these options.
For instance, for geom_col() and its argument "position", it is not obvious that the options are "stack", "dodge", "dodge2", "fill". Though for this geom, some pieces of information are included in the details, it is easy to miss.

An internal or external documentation, with or without examples, would help.
Being aware of what's available for/compatible with a geom is already a good start. We can try out the options by ourselves.

The best would be to expand the https://ggplot2.tidyverse.org/ documentation and have specific pages for each arguments with the list of different options. Maybe a list with annotations indicating which geom can use these options.

[teunbrand]

FWIW I think the documentation could be slightly improved by having topic-level documentation that (1) gives a broad overview, (2) gives common usage patterns and (3) links and lists all relevant functions/options. You could then link to that topic in specific functions/arguments that touch the topic.

I imagine 'topic'-level documentation for every part of the grammar, i.e. geoms, stats, mapping, facets, coords, theme and scales. Moreover, some more granular but widely applicable subjects might deserve their own topic-level documentation, such as position adjustments, breaks, labels, limits, transformations and guides. Perhaps the breaks, labels and transformations are more in the scope of the {scales} package however.

If you click the details button below, I've written out an example for the topic of 'guides'.

Plot guides

Description

Guides help translate visual properties of the plot back to data values. Within ggplot2, guides can be divided into two types: position guides and legend guides. Position guides give an indication what the x- and y-positions on a plot panel mean and is typically represented by an axis. Legend guides display information regarding to colour, shape and size of data and is typically represented by a legend or colour bar.

Usage

Guides are properties of scales. When you use the aes() function to set a mapping, scales are automatically added and come with default guides. To change a guide, you can use the guide argument of a scale to set a new one. Below, guide = "legend" is used to change the default colour bar to a legend, and guide = guide_axis() to change the position of the axis.

ggplot(mpg, aes(displ, hwy, colour = cyl)) +
  geom_point() +
  scale_colour_gradient(guide = "legend") +
  scale_x_continuous(guide = guide_axis(position = "top"))

As shown above with guide = "legend", quickly swapping out a default guide for another can be done using a string with the guide_-prefix omitted. To have more control over the details of a guide, for example changing the position of the x-axis, the guide_*() function can be used instead. Alternatively, guides can also be added to a plot using the guides() function:

ggplot(mpg, aes(displ, hwy, colour = cyl)) +
  geom_point() +
  guides(
    x = guide_axis(position = "top"),
    colour = "legend",
    y.sec = "axis"
  )

The look and feel of both position and legend guides can be tweaked in the theme. The relevant theme arguments have the axis- or legend-prefixes. Some styling options that are unique to a particular guide can be set in the guide_*() function.

ggplot(mpg, aes(displ, hwy, colour = cyl)) +
  geom_point() +
  guides(
    colour = guide_colourbar(barwidth = 0.5)
  ) +
  theme(
    axis.ticks.length.x = unit(5, "pt"),
    legend.title = element_text(face = "bold", size = 12)
  )

If you want to turn off a guide, you can set guide = "none" in the scale or add guides(x = "none") to a plot. All legend guides can also be turned off at once by setting theme(legend.position = "none").

Options

The ggplot2 package offers the following guides that can be used in a plot:

• Position guides
  • guide_axis() for displaying markers at some positions that indicate some value of the position in the plot.
• Legend guides
  • guide_legend() for displaying many other aesthetics such as colour, size, and shape in an arrangement of keys.
  • guide_bins() for displaying binned aesthetics as ordered keys.
  • guide_colourbar() for displaying continuous colour or fill aesthetics as a gradient of colours in a bar.
  • guide_coloursteps() for displaying binned colour or fill aesthetics as a stack of colours in a bar.

[hadley]

@teunbrand I think that sort of documentation is generally better placed in vignettes or the ggplot2 book. I think function docs are best kept as a reference, with pointers to places you can learn more about the general theory.

[teunbrand]

I can see that point, and the book and vignettes are great material. Currently though, the help pages aren't all linked up such that more information is just one click away from the documentation that you're reading. I thought this topic documentation could bridge this gap by providing a basic explanation, as well as acting as a small hub that links to relevant reading material. In case I've been somewhat unclear: I'm not suggesting this replaces function docs, it would just live as a separate doc pages (perhaps more minimal, but with more links than the example I gave).

[hadley]

Maybe the specific example you picked has lead me astray. The original motivation for this issue is to do better with the docs for stat, position, geom, and ... in geom_/stat_ functions. I think the documentation for these arguments could include more details (e.g. a paragraph instead of a sentence) and link to a more standalone documentation topic like you suggest.