8

For the time being, we don't have tag-level discussion tools for Docs, so let's use meta.

For each answer, let's store our agreed guidelines on some Topic pertaining to the R docs. To discuss and try to reach consensus, we can use

Please make each answer CW and try to avoid duplicate answers and edit wars.

For narrow issues only pertaining to one or two Topics, let's try to use the per-Topic discussion tools.

(The content below so far is temporary, filled in as an example before discussing with others.)

4 Answers 4

2

How to handle various types of Topics

To structure this: Define what the Topic type means, give some examples, then explain how we want it handled -- Do we want it here? If so, how should it be linked to other Topics or tags?

Tasks

A task is like a question in Q&A, but broader, ideally serving as a reference for many questions.

To the extent that a task relies on packages or other exotic tools, it should link to Topics for those tools. Similarly, to the extent that an Example is entirely about a given Topic (e.g., Subsetting rows and columns from a data frame is entirely about the concept of Subsetting), it should link there. Linking back and forth reduces duplication and allows Docs editors to find and fix errors more easily.

If a task is so broad that it cannot fit under a single Topic, (i) break it up into several; (ii) make a meta-task Topic; (iii) link back and forth between the meta-task and the others; and (iv) make sure each example under the meta-task still has runnable code with verbal explanations. For an example, see the meta-task Input and output, which has an example tying together Topics about various tabular-data formats; and should eventually get examples for spatial-data formats, graph data format, etc.

Tools

A tool Topic is about a data structure, function, package or other tool that can be used with R.

For packages, if it has its own tag and Docs, those should be linked prominently. If not, it is very likely that the package will require multiple topics (of various types: tasks, tools, whatever). These should all link back and forth with the "main" Topic about the package. For example, Shiny reactivity and Shiny should be linked.

For a single function, might as well try to use the Syntax and Parameters sections of the Topic page.

We should not have "List all the things" Topics, like Data Types with Examples "Logicals", "Dates", etc., for two reasons: these are not real examples and we will run out of space for them in short order (since the number of Examples is capped).

Methods

A method Topic is about a way of performing data analysis, taken from statistics or elsewhere.

If a specific package or exotic tool is used, its Docs should be linked.

If a Topic is too broad, break it up and link to a top-level Topic (like Random Forest Algorithm and Machine learning should be linked).

Concepts

A concept Topic is what it sounds like.

These should use the Introduction and Remarks section to introduce the Topic and then consist of Examples illustrating the concept. So, "Literate Programming" is not a good Example -- it belongs in the Remarks, while a real example might show how to use it to do something.

Meta

A meta Topic is about R Docs. Examples:

For now, let's leave these alone if they are on Docs. Eventually, we might want to move everything except the "Getting started" content to meta.

2

Content for examples

Each Example should contain code that runs along with verbal explanation (whether in prose or code comments) to illustrate the example. The Example should show "how can I do X?", not "what is X?"; for the latter, use Remarks and the Introduction section as much as possible.

Because each Topic has a limited number of Examples and the top Example gets all of the attention, it is tempting to shove as much as possible there and call it "Basic Usage". This is not a good idea, for fairly obvious reasons. Split an overstuffed Topic if you need to, or expect its Examples to be deleted or split by others.

Good examples

One problem, considered from multiple angles

Suppose you want to do X. In that case you can do A:

...

But you also should consider B and C for edge cases:

...

One problem with a multi-step solution

Suppose you want to do X. To get there, we will have to do A, B and then C.

Multiple similar problems

Suppose you want to do X. In that case you can do A:

...

Now suppose you want to do similar task Y (maybe with different data, or different treatment of missing values or something). We can use B for that:

...

Bad examples

Multiple entirely unrelated tasks (an example)

Suppose you want to do X. In that case you can do A:

...

Now suppose you want to do unrelated task Y (new data, new objectives). We can use B for that:

...

Now suppose you want to do unrelated task Z (new data, new objectives). We can use C for that:

...

2

Speed and efficiency

We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil. -- Donald Knuth

Documentation should focus on readability and clarity, and not get bogged down in comparing the performance of different approaches to the same problem.

If a topic is a common performance bottleneck, good practices should be demonstrated and encouraged. Examples should not show, e.g., growing an object inside a loop.

On the other hand, examples that are generally not performance bottlenecks, like creating empty data frames, do not need to present obtuse yet hyper-efficient solutions.

0

Common caveats

Might as well standardize how we address these. Hopefully, it won't be too much work to edit affected Examples when we want to change these; a google search captures the first caveat, for example.

Creating an example data file to demonstrate reading it in

Note: Before making the example data below, make sure you're in an empty folder you can write to. Run getwd() and read ?setwd if you need to change folders.

Not the answer you're looking for? Browse other questions tagged .