Making good examples

Most of the guidance for creating good examples for Q&A carries over here. Make it minimal and get to the point. Overcomplicated example data and digressions are probably counterproductive. Make it self-contained to the extent possible. If linking to external resources for reference, make sure that the example stands on its own. If linking to external resources for data, well, um, try not to; and then try some more; and then try to link only to data sources that will be around with the API you're using for a very, very long time.

Some new considerations come up for documentation:

• Refer to built-in docs like ?seq whenever relevant. We are not trying to replace those docs and want to make sure people new to R know that they are there and how to find them.
• Take advantage of the other sections. If you want to explain something about the topic (that will apply to multiple examples), then use the Remarks section.

Style

• Prompts. Do not put prompts like R>, > or + at the beginning of each line of code. These make it harder for readers to copy your code, try it out and iterate on it to learn how it works.
• Console output. For console output, the goal is to distinguish it from the code. There's no point trying to impose a particular approach to this, but here are some that are common in the R tag on SO:
  • Comment out all output, with # or ## starting each line.
  • Print as-is, trusting the leading [1] to make the output stand out from the input.
  • Add a blank line or two between code and console output.
• Code comments. It is good to explain what's going on in the code. There's no hard-and-fast rule on whether this explanation should be in prose or in code comments. Prose may be more readable and allows for longer explanations, but code comments make for easier copy-pasting. Just keep both options in mind.

Scope

As of July 2016, early in the public beta, it's still TBD what does and does not make a good example. If you want to write a tutorial rather than a simple, concise illustration, go ahead, understanding that new norms for what fits may develop.

Organization of the docs

SO has given no guidance on how they envision topics being organized, and have explained that they don't really care, since readers will come directly from search engines to a page anyways. For our own purposes, as maintainers and editors of the docs, we want to organize it so that we minimize duplication and have plenty of internal links to related examples and topics. We can figure that out as we go.

_{R PUBLIC}