Improving documentation

[eliocamp]

For a while I've seen a lot of places in which the documentation is incomplete, confusing (especially for beginners) or too complex. I see this a lot in Examples, such as the cut() Examples section which starts with:

Z <- stats::rnorm(10000)
table(cut(Z, breaks = -6:6))

This requires you to know what the rnorm() and table() functions do even before the first usage to cut(). And the result of this two lines of codes is only indirectly related to the output of cut(). A better starting example could be something very simple like just

cut(0:10, breaks = 5)

Michael McCarthy found the Example section of sqrt() and abs():

require(stats) # for spline
require(graphics)
xx <- -9:9
plot(xx, sqrt(abs(xx)),  col = "red")
lines(spline(xx, sqrt(abs(xx)), n=101), col = "pink")

which involves a lot of extra code, not relevant to the documented functions and it's not clear to me what is accomplishing.

Maybe a project could be to compile a list of these kinds of issues and improve the documentation.

[hturner]

Thanks @eliocamp for this idea. I definitely think we should have one or more groups working on documentation at the sprint.

As a first step, could you edit your post to remove derogatory language - remember that this discussion may be read by the original author(s), or their peers, so keep your criticism constructive.

A good second step would be to review the existing documentation bugs. There are 45 in that list, some triage before the sprint would already be a helpful contribution. Perhaps you can narrow down to bugs in the help files that no one appears to be currently working on. You might categorise these bugs in a similar way to on the nlme bugs project so it will be easier for people to pick up bugs that matches their expertise.

If people have new issues about the documentation they would like to see fixed, it would help if you or they could open a corresponding report on Bugzilla. That way we may get feedback from the wider community and we can track progress on each issue in the usual way. This could be done in the run-up to the sprint, or as part of the work at the sprint, as you suggest.

It would be great if you could open a PR to propose a project along these lines.

[eliocamp]

Sorry for the language. I've edited my post and I hope it's now better. Thanks for pointing this out.

[hturner]

Much better, thanks for taking the feedback on board!