R Language Meta: Documentation Guidelines Making good examples


Most of the guidance for creating good examples for Q&A carries over into the documentation.

  • Make it minimal and get to the point. Complications and digressions are counterproductive.

  • Include both working code and prose explaining it. Neither one is sufficient on its own.

  • Don't rely on external sources for data. Generate data or use the datasets library if possible:

    library(help = "datasets")

There are some additional considerations in the context of Docs:

  • Refer to built-in docs like ?data.frame whenever relevant. The SO Docs are not an attempt to replace the built-in docs. It is important to make sure new R users know that the built-in docs exist as well as how to find them.

  • Move content that applies to multiple examples to the Remarks section.